Versioning policy

Why versioning policy matters

A standards-body vocabulary is a long-lived public reference. Implementers — publishers, CRIS systems, ORCID, Crossref, evaluation systems — bind their schemas to terms in the vocabulary and need to know what stability commitments they can rely on. The versioning policy is the contract between CASRAI and those implementers. We model it on the conventions used by comparable standards bodies (notably NISO and the W3C process) and adapt them to the cadence of a small editorial operation.

Four core commitments

1. Identifiers are immutable

Every term in the Dictionary, every picklist, every object template, and every domain has a URI that resolves to the same conceptual entity for the lifetime of the vocabulary. The URI is the identifier; the slug in the URI is not free to be reused. If a term needs to change conceptually, it becomes a new term with a new URI, and the old URI is deprecated (see commitment 2) rather than retargeted. Implementers who have stored term URIs in their data can rely on those URIs continuing to mean what they meant at the time of capture.

Concretely, this means the path /dictionary/term/<slug> is a permanent identifier. We will not silently rewrite it; we will not 301-redirect it to a "replacement" term that has different semantics; we will not 404 it.

2. Deprecation, not removal

When a term is superseded, it is marked deprecated with a forward pointer to its successor. The deprecated term continues to resolve at its original URI; the response carries a deprecation banner and asameAs or replacedBy relation in the JSON-LD payload, and the deprecations page logs the chain. Implementers see the deprecation; their stored references continue to work. This rule is what makes the URIs in commitment 1 usable in practice.

The single intentional exception is removal of material that is in the dictionary in error (e.g., a term added in violation of editorial policy, or text that infringes a third party's rights). Such removals are documented in the changelog with explicit rationale, and the URI continues to resolve to a placeholder explaining the removal.

3. Semantic versioning, in the form vYYYY.N

CASRAI Dictionary releases are numbered v<year>.<n>, where n is the one-indexed ordinal of the release within the year. The current release is v2026.1 (the first release of 2026), shipped on 17 May 2026; the next release is v2026.2, targeting September 2026. This is not strictly the Semantic Versioning 2.0 contract (no major/minor/patch axis) because the dictionary's release semantics are not source-code release semantics. The convention captures what implementers actually need to track: which release a term was added in, when it was deprecated, and what corpus was current at a given date.

Within a release, version-stamped URIs are available for any implementer that wants to pin to a specific corpus snapshot:

# Current resolution (always the latest release):
https://casrai.org/dictionary/term/affiliation

# Pinned to v2026.1:
https://casrai.org/dictionary/term/affiliation?version=v2026.1
https://casrai.org/dictionary/v2026.1/term/affiliation

Both pinning forms resolve indefinitely under commitment 1. The unversioned URI is the one to use in normal consumption; the pinned URI is for archival reference (citations of "the v2026.1 definition of affiliation", for example — see the citation guide).

4. Twice-yearly stable releases

The release cadence is two stable releases per year, targeting March (spring) and September (autumn). v2026.1 ships in May as a one-time exception to align with the 2026 revival launch; the normal cadence begins with v2026.2 in September 2026. The Dictionary releases page tracks the planned dates. Between releases the dictionary is editorially frozen — new terms accumulate in the editorial queue but are not published until the next release date.

The cadence rationale is matched to implementer needs. Twice yearly is frequent enough that backlog accumulation is bounded; infrequent enough that publishers, CRIS vendors, and identifier registries can plan integration work against known release dates. The same cadence is used by the ICMJE recommendations in spirit (annual, with mid-cycle clarifications) and by several long-lived metadata schemas in scholarly communications.

Change classes inside a release

Within any release, changes are classified into four kinds, all logged in the dictionary changelog with explicit annotation:

• Addition — a new term, picklist, template, or domain enters the vocabulary at a new URI. No effect on existing implementations.
• Editorial revision — the definition, examples, or notes of an existing term are revised without changing its semantic scope. Existing implementations remain valid.
• Semantic revision — the scope of an existing term shifts materially. This is uncommon and is reviewed by the editorial board. Where the change is large enough to constitute a new concept, the old term is deprecated and a new term is added; where the change is a clarification of scope, the term is updated and the change is flagged in the changelog.
• Deprecation — a term is marked superseded with a forward pointer. The deprecations page logs the chain.

Federation versioning

Terms federated from NISO (CRediT roles), euroCRIS (Catalogue of Elements), and CODATA (RDM Terminology) carry their steward's versioning alongside the CASRAI release in which the mirror entered the dictionary. For example, a CRediT-role mirror entry in the v2026.1 Dictionary cites both ANSI/NISO Z39.104-2022 as the source version and v2026.1 as the CASRAI mirror version. When the steward revises its vocabulary, the next Dictionary release picks up the change and the changelog notes the steward-side version change.

Relationship to the all-releases catalogue

This page describes the policy; the all releases catalogue lists every release across the CASRAI Dictionary and federated standards. Implementers integrating against any of these standards should pin to specific versions in production and update on a planned cycle aligned with the twice-yearly cadence.