Publish understandable, documented open data

Estimated reading time : 3 min · Published October 1, 2026

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.

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.

Reference documents

data.gouv.fr — Bien documenter un jeu de données

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.

Test cases, expected outcomes and useful evidence
Case	Expected outcome	Evidence to retain
Advertised public download	An external person obtains a readable file without internal tools.	Address, format, size and successful opening in a common reader.
Checked field and unit	The example and full file use the same definition.	Dictionary, sample and comparison of known values across both representations.
Unknown and unmatched identifier	Limitations remain visible without substituting a plausible value.	Affected rows and documented rules for representing unknown or unmatched information.
Published correction	A 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.