Skip to content

Terminology Release Train

Intent

Coordinate terminology change with IG releases using deprecation windows and diffs.

Structure

A terminology release train coordinates changes across CodeSystems/ValueSets/ConceptMaps with predictable versions, diffs, and deprecation windows. Structurally it’s a repeatable pipeline plus documented compatibility policy.

  • Versioning policy: semver-like rules for what counts as breaking vs additive changes
  • Deprecation policy: defined windows and replacement guidance for removed/changed codes
  • Diff artifacts: human-reviewable diffs attached to releases and CI runs
  • Release notes: migration notes and implementer-facing summaries of meaning changes
  • Alignment: terminology versions aligned to IG package versions and adoption milestones

Key Components

Versioning policy

  • Define SemVer rules for terminology artifacts
  • Decide what counts as breaking vs additive
  • Align terminology versions with IG package versions
  • Keep a deprecation window policy
  • Document how implementers should upgrade

Deprecation windows

  • Provide time to migrate away from deprecated codes
  • Communicate deprecations in changelogs and IG narrative
  • Keep backward compatibility where feasible
  • Provide mapping guidance to replacement codes
  • Remove deprecated items only on major releases

Diff reports

  • Generate diffs for ValueSets/CodeSystems/ConceptMaps
  • Highlight semantic changes, not just textual changes
  • Store diffs with releases
  • Use diffs to drive review conversations
  • Validate diffs against test vectors

Migration notes

  • Provide actionable migration instructions
  • Include before/after examples when possible
  • Identify impacted profiles and tests
  • Provide cutover timelines
  • Keep notes lightweight but complete

Behavior

Release behavior

Terminology releases are treated like code releases: plan, publish, and support upgrades.

Prepare

  • Collect changes into a release candidate branch with updated test vectors.
  • Generate diffs and review for semantic impact.
  • Decide whether changes require a major/minor bump based on policy.

Publish

  • Publish artifacts with version identifiers and updated NamingSystem entries.
  • Publish migration notes including replacements and timelines.
  • Update pins used by CI in a controlled PR to keep builds deterministic.

Benefits

  • Predictable adoption
  • Fewer breaking changes

Trade-offs

  • Discipline to defer changes