Search
Enter at least two characters without personal information.

    LibraryArticles & FAQ Your projectRequest a quote
    LanguageEN
    Practical guides

    Publish understandable, documented open data

    Downloadable data is not yet understandable data. A reuser needs to know who produced it, what it covers, what it excludes and how to interpret its fields.

    Go to the method

    Notebooks, printed table and laptop on a table
    AI-generated illustration

    Establish provenance and scope

    Describe producer, collection method, time period and geographic or thematic coverage. Distinguish extraction, update and measurement dates. A file published today may describe an earlier measurement; publication does not change its reference year.

    State missing areas and approximate values where the source identifies them. Do not fill a gap with an undisclosed estimate. data.gouv.fr’s documentation guidance addresses production context, structure and possible inconsistencies.

    Provide a dictionary and example

    Explain each field, unit, type, missing value and reference code. Supply a small readable example consistent with the full dataset. Where identifiers join tables, document relationships and potentially unmatched rows.

    Distinguish entities from their labels. A municipality may have several postal codes and a product several variants. Documentation should help prevent misleading aggregation or deduplication that removes a useful relationship.

    For geographic data, document the coordinate reference system and order, not only the format name. RFC 7946 defines GeoJSON using WGS 84 decimal degrees; a position’s first two values are longitude then latitude. In a fictional exercise, a Point at [2.35,48.86] must not become [48.86,2.35]. Both arrays are parseable JSON and the numbers remain plausible: syntax validation alone will not detect the swap.

    Distinguish an unlocated feature from a known point. An unlocated GeoJSON Feature may have geometry set to null; this is not a Point with null coordinates, nor replacing unknown data with [0,0], which is a real position. Also explain what the point represents: observed entrance, geocoded address or calculated centre, with provenance and date. Adding decimal places does not make an estimate more certain.

    Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.

    Fictional exercise: check meaning beyond parseable JSON
    CaseInterpretationUseful check
    Point · coordinates: [2.35,48.86]Longitude 2.35; latitude 48.86Compare with named source fields
    Point · coordinates: [48.86,2.35]Two plausible numbers, reversed in this exerciseCheck meaning; syntax alone is insufficient
    Feature · geometry: nullUnlocated feature; structure fragmentDocument the missing value without inventing a point
    Position [0,0]Existing coordinates, not absenceDo not automatically substitute it for unknown data

    Check publication and reuse

    Identify source reuse conditions and attribution information to retain. Have appropriate reviewers assess publication rights and possible personal data before public release. An address visible elsewhere does not automatically make every copy suitable for publication.

    Test downloads without internal tools or special accounts when public access is promised. Check format, encoding and integrity. Provide a version reference or checksum so feedback can be tied to the downloaded file.

    Maintain versions and corrections

    Choose a realistic review frequency and a contact for issues. Describe added, removed or redefined fields when schemas change. Distinguish corrections from new measurements to avoid creating false changes in a time series.

    Retain useful versions and notes with a clear replacement policy. Publication documentation should let another person reproduce extraction or understand its limitations. A download counter does not replace documentation quality.

    Primary documentation : data.gouv.fr : Bien documenter un jeu de données.

    Distinguish a dataset from its distributions. A CSV and JSON file may represent the same dataset in two formats; do not automatically count them as two independent measurements. DCAT describes a distribution as a specific representation of a dataset. Still compare coverage, precision, fields and version: two distributions are not necessarily equivalent without information loss.

    Add a version identifier and a history explaining corrections. A “latest version” address can remain stable, but the version actually used must be identifiable. Also distinguish a correction from a new observation: measuring a new month does not by itself correct the previous month. Explain this relationship between versions and series before comparing figures.

    Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.

    Data publication: identify the object, format and revision
    Documentation elementWhat it distinguishesUseful check
    DatasetThe subject, scope and observations described.Its identity remains understandable independently of file format.
    CSV or JSON distributionA specific representation of the dataset.Compare fields, precision and coverage before assuming equivalence.
    Identified versionA precise state and its change history.Retrieve the cited version even if a current address has been updated.
    Correction or new periodA revised value or a different observation.Do not present a new month as an automatic correction of the previous one.

    Reference documents

    Content updated on

    Documented reference points for this topic

    Documented reference points for this topic
    ReferenceValue or syntaxScope
    RFC 4180 · CSV
    text/csv · "a,b"Fields containing commas, quotes or line breaks are quoted; internal quotes are doubled.
    RFC 8259 · JSON
    application/json · UTF-8Standard JSON permits neither comments nor trailing commas; strings use double quotes.

    Dates indicate when references were consulted. These facts are neither a site audit nor an overall compliance statement.

    Acceptance matrix to adapt to your project

    These proposed checks use synthetic cases. Decide the required behaviour with the team, record the result and assign unresolved gaps before release.

    Scroll the table horizontally to read every column. With a keyboard, focus the table area and use the arrow keys.

    Test cases, expected outcomes and useful evidence
    CaseExpected outcomeEvidence to retain
    Advertised public downloadAn external person obtains a readable file without internal tools.Public URL, applicable licence, format, version and readability check of a representative sample.
    Checked field and unitThe example and full file use the same definition.Dictionary, sample and comparison of known values across both representations.
    Unknown and unmatched identifierLimitations remain visible without substituting a plausible value.Affected rows and documented rules for representing unknown or unmatched information.
    Published correctionA reuser can distinguish a correction from a new measurement.Version, change description and reference dates retained with the published file.

    Frequently asked questions

    Which date should accompany a file?

    Where relevant, show extraction, last modification and covered period as separately named dates. Do not automatically present download time as the reference year of a population or another measurement.

    Does a licence alone make data usable?

    It defines reuse conditions, but fields, units, identifiers, coverage, quality and versions also need explanation. Another person should be able to reproduce or at least understand the use.