How Should a Dataset Version Be Represented?
From the earlier reference collection. Read the current software blog.
Give every published snapshot a clear release identifier and explain how clients can relate it to the data they downloaded.
A file needs a recognizable snapshot
A dataset can change after download: a correction may alter a value, an entity may be added, or a schema may evolve. Without a release identifier, a user may have trouble explaining which snapshot produced a chart or reproducing a result later.
Include a version string or release date in a manifest, metadata file, or response header that travels with the data. For a downloadable archive, a version in the filename can help people identify it, but it should agree with the metadata inside the archive.
Choose a scheme that conveys change
A date-based version, such as 2026-10-28, can identify a daily snapshot if each date is published at most once or the release includes a time or revision suffix. A sequence such as v4.2 can distinguish planned revisions, but only if the publisher documents what each part means.
Do not imply compatibility rules with a familiar numbering scheme unless they are actually followed. If schema changes and data corrections use different version tracks, label both so a client can tell whether the structure changed, the records changed, or both.
Keep release identity with provenance
A useful manifest can record the release ID, publication time, schema version, and source coverage period. These are distinct facts: publication time says when the snapshot became available, while coverage period says which observations it contains.
For example, an archive named readings-2026-10-28-r2.zip could include a manifest stating that it is revision two of that day’s snapshot and identifying the schema version. That lets a user distinguish a corrected reissue from the original download.
Make old versions understandable
Document where clients can obtain release notes and how long older snapshots remain available. If old files are replaced at a permanent URL, record the version in the response metadata or preserve a checksum and release manifest so users can verify what they received.
A version label is most useful when it is consistent, visible, and tied to the actual content. It gives analysts a reproducible reference and gives software a reliable way to detect when a dataset has changed.