On this page
Separate the identities
The source dates in this guide identify documentation checks on 22 October 2026, not original publication dates. Follow each citation for the standard or documentation edition being discussed.
Teams often call three different things a “version”: the continuing collection, one frozen release, and an export package. The cited vocabulary’s version relationships are useful context for keeping those identities connected without pretending that a standard dictates your local names World Wide Web Consortium, (opens in a new tab).
| Identity | What it represents | Example value to choose locally |
|---|---|---|
| Dataset identity | The continuing collection or product being described | archive-family |
| Release version | One frozen state of that collection | [version-id] |
| Export package | A delivery containing one or more files from that release | [package-id] |
The bracketed values are placeholders, not prescribed names. Use a stable internal convention and document it. A package can be rebuilt from the same release without becoming a new dataset version if the bytes and declared scope are unchanged. Conversely, a new release may be required when records, schema, interpretation, rights scope, or exclusions change, even if the folder name looks similar.
Keep a file manifest beside each release. The manifest identifies bytes, while the change log explains the relationship between releases. If either one is overwritten, a later reviewer loses part of the evidence chain.
Record one release in a durable shape
At minimum, a release record should contain the fields below. An internal evidence reference can point to the controlled record without copying the record into a public example.
| Field | What to record | Why it matters |
|---|---|---|
dataset_id | Stable local identity | Connects releases without changing the release identifier. |
version_id | Exact release label | Gives the release a reference that can be cited. |
previous_version_id | Prior release, or not applicable for the first | Makes the lineage explicit. |
released_at | Release time with an offset or UTC form | Separates release timing from event-time coverage. |
source_coverage | Period, geography, and source scope | Prevents a release label from hiding a scope change. |
schema_version | Structure expected by consumers | Lets readers distinguish field changes from row changes. |
manifest_ref | Internal reference to the exact file manifest | Connects the explanation to byte-level evidence. |
change_type | Content, schema, semantic, provenance, rights, or packaging | Makes review questions visible. |
change_summary | Plain-language description | Tells a reviewer what to compare. |
compatibility | Compatible, review required, or not assessed | Keeps uncertainty explicit instead of implying compatibility. |
Do not put a personal name, customer record, secret, or private storage URL into a public example. Keep the raw dataset and private evidence in controlled storage, and point to them with a reference that the intended reviewer can resolve.
Classify and log each change
“Updated data” is too vague for a handoff. Use a change category and a concrete comparison. A single release may have several entries. For example, a new field can be a schema change and a semantic change, while a corrected timestamp can be content and provenance. Record both when both affect a reader’s decision.
- Content: records were added, removed, corrected, or retracted.
- Schema: a field, type, nullability rule, delimiter, encoding, or relationship changed.
- Semantic: a field keeps its name but its definition, unit, code list, or interpretation changed.
- Provenance: the source, extraction rule, transformation, or exclusion policy changed.
- Rights and privacy: authority, terms, consent or notice evidence, retention, redaction, or intended use changed.
- Packaging: files were split, renamed, compressed, re-encoded, or rearranged without a claimed content change.
The categories are an editorial method. They do not establish that a release is safe or licensed. Link each entry to the comparison and review evidence that supports its description.
Append-only record shape
{
"dataset_id": "[stable dataset identity]",
"version_id": "[new release]",
"previous_version_id": "[previous release]",
"released_at": "[RFC 3339 timestamp]",
"manifest_ref": "[controlled evidence reference]",
"changes": [
{
"type": "[content|schema|semantic|provenance|rights|packaging]",
"scope": "[file, field, or defined collection scope]",
"summary": "[what changed in plain language]",
"evidence_ref": "[comparison or review reference]",
"compatibility": "[compatible|review required|not assessed]"
}
],
"known_limits": [
"[unverified field, source gap, or out-of-scope question]"
]
}Append a new release record instead of editing the previous record in place. If a record must be corrected, preserve the correction reason and the evidence reference. A change log is not a marketing summary and should not turn a missing comparison into a claim that nothing changed.
Compare before you publish the next release
- Freeze the outgoing release reference and its manifest.
- Create the candidate release in separate controlled storage.
- Compare file paths, byte digests, schema fields, data types, code lists, time coverage, and exclusions.
- Classify each difference and link its evidence.
- Recheck rights, privacy, contractual, and intended-use boundaries where the change affects them.
- Write the new change-log entry and name unresolved questions.
- Publish or share the release only under the owner’s existing approval process.
The cited provenance model describes entities, activities, agents, and relationships for how an entity was generated World Wide Web Consortium, (opens in a new tab). You do not need to implement that model to keep a useful log, but it is a reminder to record the activity and source context behind a release, not just its final label.
Keep release history separate from legal conclusions
A version chain can show that a file, schema, or scope changed. It cannot prove that the owner had authority to make the change, that every contributor agreed, or that the new release is suitable for a model. Preserve title, authority, terms, privacy, exclusions, and intended use as separate evidence. If a rights boundary is unresolved, write review required or an equivalent explicit state; do not hide it in a vague change note.
The data provenance log organizes source, rights, processing, and exclusion evidence. The data handoff guide covers custody and continuity questions. The broader export guidance covers tool-specific export quality; this guide owns release lineage and change explanation.
After a release history and evidence references are organized, an eligible owner can use the Rightmark appraisal path as a qualified preparation reference. It does not register versions, compare manifests, approve a release, or create a licensing offer. Keep the raw dataset and private evidence out of the public worksheet.