Every team that ships a FHIR integration eventually has data that does not fit the base spec. The instinct is to reach for extensions, and that instinct is right more often than it is wrong. But not every gap deserves an extension, and the choice between "use an extension" and "use a different mechanism" is where a lot of quiet interoperability debt gets born. The site's Extension registry audit classifies every extension it sees against major registries. For the wider setting, FHIR resources for US digital health has more.
The Base-Spec Check Comes First
Before reaching for an extension, check whether the base spec already covers the element. A gender-identity field is not an extension on Patient — it is a specific element on newer versions or a US Core extension. A preferred language is not an extension — it is on Patient directly.
The extension audit catches this: it flags custom extensions that duplicate base elements. Every one it flags is a decision to reconsider.
Extensions Are For Genuine Gaps
Reach for an extension when:
- The data element is not in the base spec
- No existing public extension covers it
- The data belongs on this resource type, not somewhere else
- Downstream consumers can be told about it
If all four are true, an extension is the right answer. If any is false, there is usually a better mechanism.
When It's A Different Resource, Not An Extension
Some data belongs on a related resource, not as an extension on this one. Employment status usually belongs on RelatedPerson or Observation, not as a Patient extension. Insurance information belongs on Coverage, not on Patient. Family history belongs on FamilyMemberHistory.
Adding an extension for something that could be a related resource is the shortcut that costs more later. The related resource carries queryable, indexable structure. An extension does not — it lives in the resource that hosts it.
When It's A Profile Rule, Not An Extension
Sometimes the gap is a rule, not a field. "This Patient must have an MRN identifier" is a profile rule, not an extension. Slicing on Patient.identifier with a required MRN slot is the profile mechanism. For the profile mechanic, reading an IG for the extensions you actually need is the entry.
When Modifier Extensions Are The Right Choice
A regular extension carries information a receiver may safely ignore. A modifier extension carries information a receiver must understand or reject. The distinction is not stylistic — it decides whether a compliant receiver can drop the element.
Do-not-resuscitate status is a modifier extension. Race categorization is a regular extension. Getting the type wrong produces payloads that are silently unsafe. For the split, extensions vs modifier extensions: the modelling difference that matters covers the mechanic.
When A Public Extension Exists
Before minting a private extension, check the public registries. HL7 base, US Core, IPS, SDC, VRDR, SMART, CARIN, Da Vinci — each publishes a set of extensions with well-known URLs. If one covers the gap, use it. Consumers may already recognize it.
The audit tool at /lint-lab/audit-extension-urls/ matches every extension URL it sees against those registries. Extensions that match are known-good; extensions that do not are candidates for either registration or private-only use.
When A Custom Extension Is Unavoidable
Sometimes no public extension fits. That is fine. The custom-extension checklist:
- Publish a StructureDefinition with a stable canonical URL
- Document the value type and cardinality
- Document the meaning in plain language
- Publish the definition at a URL your consumers can find
- Version the URL if the meaning may drift
For the deeper picture of what a public API costs when you take this route, custom extensions in a public API: hidden costs covers the trade-offs.
What Not To Do
- Do not use extensions for data that fits a base spec element
- Do not use regular extensions for data a receiver must not ignore
- Do not invent inline extensions with no StructureDefinition
- Do not confuse extension URLs with resolvable network locations — they are identifiers
The Short Version
Extensions are the right answer when the gap is real, no public extension exists, and the data belongs on this resource. Everything else has a better mechanism — a base element, a related resource, a profile rule, or an existing public extension. The audit tool tells you which category you are in.
Sources
- HL7 canonical FHIR extensibility chapter - HL7 canonical FHIR extensibility chapter, evergreen reference