Versioning
Managing changes to content over time—when to create new versions, how to version, and how to maintain compatibility.
Why Versioning Matters
Versioning enables:
- Persistence: Old references remain valid
- History: Understanding what changed and when
- Compatibility: Systems can adapt at their own pace
- Audit: Tracing the evolution of content
Substantive vs Non-Substantive Changes
The standard distinguishes between changes that require a new version and those that don't—but the distinction requires interpretation. The threshold for what is "substantive" depends on your register's risk profile.
Risk-Based Thresholds
Low Risk
Only major meaning changes are substantive. Typos, formatting, and minor clarifications don't require versions.
High Risk
Any meaningful change is substantive. Even typo fixes that could change interpretation require versions.
What the Standard Says
A substantive change is one that has a major impact on the use of the concept or register item. A non-substantive change has minor or no impact on use.
The Challenge
"Major impact on use" is subjective. What breaks one consumer may be transparent to another. Here's a decision framework:
Decision Tree
- Does this change the identifier?
- Yes → This is not a change, it's a new item
- No → Continue
- Does this change what the item means?
- Yes → Substantive (create new version)
- No → Continue
- Could existing references become incorrect or misleading?
- Yes → Substantive (create new version)
- No → Continue
- Does this affect validation or processing rules?
- Yes → Likely substantive
- No → Non-substantive
Examples
| Change | Type | Rationale |
|---|---|---|
| Fixing a typo in description | Non-substantive | Meaning unchanged |
| Adding an optional field | Non-substantive | Existing use unaffected |
| Changing a code value | Substantive | References using old value break |
| Changing definition significantly | Substantive | Meaning changed |
| Marking as deprecated | Non-substantive | Still valid, just discouraged |
| Removing a required field | Substantive | Breaks systems expecting it |
| Adding a new example | Non-substantive | Supplementary information only |
Versioning Schemes
Choose a scheme that matches your content and users:
Semantic Versioning
MAJOR.MINOR.PATCH (e.g., 2.1.3)Communicates change impact through version number.
- MAJOR: Breaking changes
- MINOR: New features, backward compatible
- PATCH: Bug fixes, backward compatible
Best for: APIs, software-like content
Date-Based
YYYY-MM-DD or YYYYMMDDSimple, unambiguous, sortable.
- Clear when version was created
- Easy to sort chronologically
- No semantic meaning
Best for: Time-sensitive reference data
Sequential
v1, v2, v3 or 1, 2, 3Simple counter, no embedded meaning.
- Easy to understand
- Ordering is clear
- Requires external documentation for meaning
Best for: Internal use, simple registers
Hash-Based
a1b2c3d4Derived from content, ensures uniqueness.
- Guaranteed unique for content
- Detects accidental duplication
- Not human-readable
Best for: Content-addressable systems, git-like
Version Compatibility
When you release a new version, what happens to systems using the old one?
Compatibility Types
| Type | Definition | Example |
|---|---|---|
| Backward Compatible | New version works with old consumers | Adding optional fields |
| Forward Compatible | Old version works with new consumers | Ignoring unknown fields |
| Breaking Change | Old consumers fail with new version | Removing required fields |
Managing Breaking Changes
- Communicate early: Warn users before making breaking changes
- Provide migration path: Document how to adapt
- Overlap periods: Support both versions during transition
- Sunset old versions: Clear timeline for deprecation
Version Lifecycle
Versions progress through states:
Created but not yet approved
The active, recommended version
Still works, but migrate away
Replaced by newer version
No longer available for use
Versioning Anti-Patterns
Version Everything
Creating a new version for every typo fix or minor edit.
Consequence: Version explosion, user confusion.
Better: Batch minor changes, version meaningfully.
Never Version
Modifying content in place without creating versions.
Consequence: Lost history, broken references.
Better: Version substantive changes.
Delete Old Versions
Removing old versions to save space.
Consequence: Broken citations, lost history.
Better: Archive, don't delete.
Semantic Versioning for Non-Semantic Content
Using MAJOR.MINOR.PATCH for content where the distinctions don't apply.
Consequence: Confusing version numbers.
Better: Match scheme to content type.