Every FHIR resource has fields the spec author picked. Every implementation has data the spec author did not pick. The FHIR answer to that mismatch is the extension model, and it is the mechanism that keeps the spec small enough to stay interoperable while still letting implementations carry the fields they need. The site's R4 resource atlas surfaces the common extensions per resource. For the wider FHIR framing, more on healthcare integration patterns has more.
What an Extension Is
An extension is an element on any resource that carries a URL (the extension's canonical definition) and a typed value. Every DomainResource has a Resource.extension array that holds any number of extensions. Every element that is a BackboneElement carries its own extension array too. That gives implementations a place to put anything the base spec did not cover, at any level.
The Rules
Extensions are defined by StructureDefinition resources. Every extension has:
- A canonical URL that identifies it uniquely
- A datatype for the value
- A description that says what it means
- An optional set of allowed contexts (which resources it can appear on)
Populating an extension without a StructureDefinition definition is a common shortcut that costs more than it saves. Downstream systems have no way to interpret it, and validators reject it.
When To Use an Extension
Reach for an extension when:
- The data element is not in the base spec
- The data element does not fit any existing extension in a public IG
- The data is small and structured — not a whole substructure
- The data belongs on this resource type, not on a sibling
If the answer is "the base spec has an element for this," use the base element instead. Extensions are the escape hatch, not the default.
Extensions Come in Two Flavors
Regular extensions are informational. Consumers may ignore them without breaking correctness.
Modifier extensions change the meaning of the parent element. Consumers must understand them or reject the resource. Modifier extensions live under modifierExtension and are the FHIR mechanism for content that a receiver cannot safely ignore.
Using a modifier extension when a regular one would do is the more common mistake. The alternative — using a regular extension for content that changes meaning — is worse.
Publish Your Own Extensions
An implementation that invents extensions on the fly ends up with a private vocabulary that other teams cannot use. The healthier pattern is to publish a StructureDefinition for each custom extension, versioned under a stable canonical URL. Consumers can then interpret them consistently. For the profile mechanic that hosts your extensions, profiles and slicing at a glance is the entry.
Extensions and Must-Support
Profiles routinely mark specific extensions as mustSupport. That means implementers have to handle the extension — even though the base resource does not require it. For the deeper picture of how must-support interacts with the extension model, must-support elements and what implementers actually do covers it.
Extension URLs Are Not Namespaces
The canonical URL is an identifier, not a network location. It does not need to resolve. Publishing a real definition at the URL is a courtesy; the identifier itself is what matters. Confusing the two produces extensions that break when the network changes but the meaning does not.
The Short Version
Extensions fill the gap between what the base spec covers and what your implementation needs. Publish definitions. Use modifier extensions only when the receiver cannot ignore them. Prefer the base element when it exists.
For the base pattern that hosts all of this, reference vs contained: when to embed and when to link covers the sibling composition mechanism.
Sources
- HL7 canonical R4 extensibility chapter covering regular and - HL7 canonical R4 extensibility chapter covering regular and modifier extensions
