FHIR ValueSets bind coded fields to permitted values, and getting ValueSet governance right is where CMS-0057 attestation is won or lost. Four patterns cover most production deployments.
Pattern 1: Version-pinned ValueSets. ValueSet.compose.include.system references code system versions explicitly (http://snomed.info/sct|20240301). Prevents terminology drift when SNOMED releases update. The US Core profile references specific ValueSet versions; align with the profile.
Pattern 2: Cached expansions. ValueSets with SNOMED-based hierarchies can expand to tens of thousands of codes. Cache expansion in Redis or the server's cache layer; regenerate on terminology update.
Pattern 3: Local ValueSets for site-specific vocabularies. Community-defined codes (department names, custom order types) live in local ValueSets that reference internal CodeSystems.
Pattern 4: Composed ValueSets for cross-terminology unions. Some clinical concepts need ValueSets that combine SNOMED + LOINC + local codes. Use include.valueSet references to compose.
Governance workflow
| Step | Cadence | Owner |
|---|---|---|
| SNOMED CT release | Quarterly | Terminology admin |
| LOINC release | Twice yearly | Terminology admin |
| ValueSet regeneration | Following terminology release | Terminology admin |
| Cache invalidation | On regeneration | Automated |
| Downstream notification | On version bump | Automated |
| Application update | Bimonthly | Dev team |
Common ValueSet mistakes
1. Unversioned bindings. Applications reference ValueSets without version, drift silently. 2. Runtime expansion. `$expand` at query time is expensive. Cache expansions instead. 3. Missing cross-map. ValueSets that reference multiple code systems without ConceptMaps for translation. 4. Hardcoded lists in code. Application code that embeds ValueSet contents statically drift from server-side ValueSet updates.
Tooling
Ontoserver, HAPI's terminology module, and Aidbox Terminology all support the four patterns. Pick based on ecosystem fit.
ValueSet governance is a subsystem, not a one-time task. Treat it as such and CMS-0057 attestation gets easier every year.
