Dataset versioning gives each state of a dataset its own identifier, so an earlier state can be retrieved and a result can name the exact data it used [1, 2, 3]. Sources keep changing after capture. In February 2026 the U.S. Bureau of Labor Statistics (BLS) revised its March 2025 estimate of seasonally adjusted total nonfarm employment by −898,000, or −0.6 percent [31]. Pew Research Center found that 38% of webpages that existed in 2013 were no longer accessible in October 2023 [32].
This note sets out the mechanics from published standards, specifications and tool documentation. Tool defaults are as documented on 8 November 2026.
Why dataset versioning starts with the source
The BLS benchmarks its employment survey each year to counts drawn mainly from unemployment insurance records, and over the prior decade that revision averaged 0.2 percent in absolute terms [31]. A quarter of all webpages that existed at some point between 2013 and 2023 were no longer accessible in October 2023 [32]. Terms move too. An audit of 14,000 web domains found that in a single year, 2023 to 2024, about 5% or more of all tokens in the C4 web corpus became fully restricted from use, and that terms of service restricted crawling for 45% of it [33].
Some sources change by the second. The SEC's EDGAR APIs are updated as filings are disseminated, with a typical delay under a second for submissions and under a minute for XBRL data, and the bulk files are republished nightly at about 3:00 a.m. ET [30]. An extract taken once from any of these sources soon stops matching them.
Revision and release are separate acts
A CODATA paper published in 2021, built on 39 use cases from 33 organizations, separates two acts [1]. A revision is any change to the bitstream of a dataset. A release is an editorial choice to publish one revision for reuse, and "Not all revisions lead to a new release" [1]. Each revision gets its own identifier. Each release comes with a description of what changed, why it matters and what it implies for use [1].
The Research Data Alliance (RDA) adds the means: store data "in a versioned and timestamped manner" and give persistent identifiers to timestamped queries that can be re-run against that store [2]. The W3C asks for a version number or date on each dataset and a complete version history [3]. The W3C's catalog vocabulary leaves the choice of when a change makes a new version to the data provider [4], so that rule is the publisher's to write down and publish [1].
Two time axes: valid time and system time
A record carries two times. SQL:2011 calls them application time, the period a fact is believed valid in the real world, and system time, the period the database held it [13]. In a system-versioned table, every update or delete keeps the old row, and users cannot change historical rows [13]. A bitemporal table keeps both periods, as in Kulkarni and Michels's example of a legal name change recorded in the database after it took effect [13].
State the period convention. SQL:2011 uses closed-open periods [13], and the FRED API's real-time periods are closed at both ends [15]. FRED's real-time period "marks when facts were true or when information was known until it changed" [15], and ALFRED retrieves each release, or vintage, that was available on a past date [16]. The capture time that every record needs sits inside a provenance standard for datasets that state their limits.
How long time travel keeps history
Open table formats keep history as snapshots. In the Apache Iceberg spec, a snapshot is the state of a table at a point in time, and from format version 2 each snapshot records its operation: append, replace, overwrite or delete [18]. Rebuilding a state from a snapshot and the changes after it is also the method behind rebuilding an order book from snapshots and diffs.
Snapshots and history expire, on these documented defaults:
| System | Default history kept | Basis |
|---|---|---|
| Iceberg snapshots, when expiry runs | 5 days, at least 1 snapshot | [19, 21] |
| Iceberg branches and tags | Forever | [20] |
| Delta Lake log | 30 days | [22] |
| Delta Lake deleted data files | 7 days | [22] |
| Snowflake | 1 day, up to 90 days for permanent objects on Enterprise Edition and higher | [23] |
| BigQuery | 7 days, settable from 2 to 7 | [24] |
Expired Iceberg snapshots are no longer available for time travel queries [21]. Delta Lake can travel back to a version only while both its log and its data files are kept [22]. Past the window, a permanent Snowflake table's history moves into Fail-safe, where only Snowflake can recover it, for 7 days in Snowflake's worked example [23], and BigQuery's fail-safe period of seven days cannot be configured or extended [24]. Apart from Iceberg's branches and tags, these defaults run from 1 day to 30 days (derived) [19, 22, 23, 24]. A version that a published result cites needs its own retained reference, such as a named tag, an export with a checksum or a stored query (derived) [2, 20, 22].
Several tools pin a state by content or by name. Git names each object by a SHA-1 checksum of its content [25]. DVC records an MD5 hash for files on local and SSH storage [26], MLflow computes a digest for each logged dataset [27], and the Hugging Face Datasets library loads a dataset at a Git tag, branch or commit [28].
Version numbers for data
Semantic Versioning defines MAJOR.MINOR.PATCH for software and states that a released version's contents "MUST NOT be modified" [9]. Croissant, a dataset format specification from MLCommons, applies the same scheme to data in its version 1.1 of 29 January 2026 [10]:
- PATCH: the data stays the same and is serialized or packaged differently.
- MINOR: existing data is unchanged and retrievable as before, with new fields, record sets or records added.
- MAJOR: existing data was edited, removed or moved across splits.
For a live dataset, Croissant drops checksums on files expected to change and asks applications to filter by date [10]. In its stock-price example, rewritten history calls for a version update, and an append to the current, incomplete year does not [10].
One published changelog applies such rules loosely. FineWeb, a public web-text training dataset, moved to v1.1.0 after reprocessing 11 dumps to fix a deduplication bug, and to v1.3.0 after processing missed documents and removing specific domains in response to a cease-and-desist notice [12]. Under Croissant's rules both releases changed existing data, which reads as MAJOR (derived) [10, 12]. Each changelog entry states what changed, and only those two also say why [12].
Point-in-time correctness and look-ahead bias
The FISD Alternative Data Council defines point-in-time data as history that reflects "what was known and when it was known" [29]. Look-ahead bias comes from using data that became known only after the date analyzed, and survivorship bias from a universe that represents only the present [29]. The SEC's frames API returns, for each entity, the fact last filed for the period requested [30], so a study of what was known on a past date needs its own dated copies (derived). Matching one entity across sources that each revise is its own step, covered in how entity resolution matches records across sources.
Withdrawn records need a notice
Deletion is a version too. The W3C asks publishers who remove data to keep its identifier, answering 410 (Gone) for deleted data or pointing to the archive that holds it [3]. The RDA allows deletion under a policy, after which queries may no longer re-run against their original timestamp, only against the current one, and asks that landing pages persist [2].
A withdrawal without a clear notice leaves the data in use. Two datasets retracted in April 2019 kept circulating: in the authors' 20% sample, one and its derivatives were used 54 times in papers published in 2020, and the other with its derivatives 73 times [35]. The authors found that the creators had not clearly stated that the datasets should no longer be used [35]. A 2022 framework for deprecating datasets proposes a central repository that tracks dataset modifications and deprecations [34]. What a capture record holds from the start is set out in collecting training data: sources, terms and capture records.
Data versioning best practices: a checklist
- Publish the versioning policy: what counts as a revision, a release and each version level [1, 4].
- Keep valid time and capture time on every record, with the period convention stated [13, 15].
- Pin each cited version with a tag, a checksum or a stored query, since time travel windows expire [2, 19, 22].
- Number releases with written MAJOR, MINOR and PATCH rules for data [10].
- Ship each release with a change record that says what changed, why it matters and what it means for use [1, 3].
- Keep the identifiers of withdrawn records, with a notice to stop using them [3, 35].
Rillor's data collection for model training keeps each record's capture time, keeps a source's change as a new version and delivers the dataset with its capture log, its source list with terms and its version history. A team with its versioning rules worked out can send the coverage it needs and how often the data should update.
Read the full report
The full report adds the CODATA and RDA principles in detail, SQL:2011's query forms, a mapping from table operations to version levels, the fields of a change record and the complete source list.