Estimated reading time : 5 min · Published
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.
| Case | Interpretation | Useful check |
|---|---|---|
| Point · coordinates: [2.35,48.86] | Longitude 2.35; latitude 48.86 | Compare with named source fields |
| Point · coordinates: [48.86,2.35] | Two plausible numbers, reversed in this exercise | Check meaning; syntax alone is insufficient |
| Feature · geometry: null | Unlocated feature; structure fragment | Document the missing value without inventing a point |
| Position [0,0] | Existing coordinates, not absence | Do 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.
| Documentation element | What it distinguishes | Useful check |
|---|---|---|
| Dataset | The subject, scope and observations described. | Its identity remains understandable independently of file format. |
| CSV or JSON distribution | A specific representation of the dataset. | Compare fields, precision and coverage before assuming equivalence. |
| Identified version | A precise state and its change history. | Retrieve the cited version even if a current address has been updated. |
| Correction or new period | A revised value or a different observation. | Do not present a new month as an automatic correction of the previous one. |
- W3C DCAT 3 : Distributions
Consulted on 22 October 2026; datasets versus representations and possible differences in fidelity.
- W3C : Data on the Web and versioning
Consulted on 22 October 2026; version identifiers, history and observations from different periods.
Reference documents
- W3C : Data on the Web Best Practices · Source consulted
- IETF : GeoJSON RFC 7946 · Source consulted
- data.gouv.fr : Bien documenter un jeu de données
Content updated on
Documented reference points for this topic
| Reference | Value or syntax | Scope |
|---|---|---|
| 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-8 | Standard 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.
