Skip to content

Three-Layer Terminology Model

Intent

Separate CodeSystem/ValueSet/ConceptMap roles to reduce semantic drift.

Structure

The three-layer terminology model separates the responsibilities of CodeSystems (identities and code definitions), ValueSets (selection/binding), and ConceptMaps (translation/mapping). Structurally it prevents mixing concerns and makes change impact easier to manage.

  • CodeSystem layer: authoritative definition of codes, governance, identifiers, and versioning
  • ValueSet layer: curated sets for binding; composable inclusion rules; expansion expectations
  • ConceptMap layer: mappings between code systems with explicit equivalence policies
  • Identifier publication: NamingSystem entries for key URIs/OIDs so implementers can resolve them
  • Test assets: vectors and CI checks that exercise expansions, lookup, and validate-code

Three-Layer Terminology Model Diagram

Key Components

CodeSystem strategy

  • Decide when to reuse vs create code systems
  • Define ownership and publication process
  • Ensure identifiers and versioning are stable
  • Document scope and intended use
  • Provide examples and test vectors

ValueSet governance

  • Define inclusion rules and expansion expectations
  • Pin and test expansions where interoperability risk is high
  • Document intent and usage constraints
  • Keep ValueSets small and composable when possible
  • Track changes with diffs and release notes

ConceptMap policy

  • Define mapping purposes (translation, reasonable mapping, etc.)
  • Set rules for equivalence and unmapped handling
  • Provide test cases for high-risk mappings
  • Version maps with terminology releases
  • Document known limitations

NamingSystem

  • Use NamingSystem to publish key identifiers
  • Avoid duplicate identifiers across packages
  • Document OIDs/URIs and their governance
  • Ensure consistent use across examples and artifacts
  • Keep identifier policy in governance docs

Behavior

Terminology authoring behavior

Changes flow through stewardship: define → test → publish → monitor.

Define and review

  • Define codes in CodeSystems with clear scope; avoid sneaking selection rules into CodeSystem content.
  • Define ValueSets as selection logic; document intended binding strength and usage.
  • Define ConceptMaps with explicit equivalence rules and unmapped handling.

Test and publish

  • Run expansion/validate-code tests in CI against a pinned terminology environment.
  • Publish terminology artifacts as part of a release train with diffs.
  • Monitor for implementer feedback and update maps/value sets with controlled change.

Benefits

  • Semantic stability
  • Better mapping

Trade-offs

  • Needs stewardship

References