Skip to main content
Spec reference: https://hl7.org/fhir/extensibility.html | https://hl7.org/fhir/extension.html
FHIR is designed to be extended. Extensions let you add data that isn’t part of the base resource definition while staying interoperable (because the meaning is anchored by a canonical URL).

​
The rule of thumb

If you can represent something using the base model, do that first. If you can’t, use an extension — and define it in a profile/IG so others can understand it.

​
What an extension looks like

An Extension always has:
  • url: a canonical URL that defines the meaning
  • exactly one value[x] or nested extension[] elements
Simple example (single value): 
{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "http://example.org/fhir/StructureDefinition/patient-favorite-color",
      "valueString": "blue"
    }
  ]
}
Complex example (nested extensions): 
{
  "url": "http://example.org/fhir/StructureDefinition/patient-preferences",
  "extension": [
    { "url": "language", "valueCode": "en" },
    { "url": "contact-method", "valueCode": "sms" }
  ]
}

​
extension vs modifierExtension

Both are valid extension points, but they have different intent:
  • extension: adds information without changing the meaning of existing elements
  • modifierExtension: changes the meaning/interpretation of the resource
modifierExtension is intentionally strict: consumers must check and understand it. If a consumer ignores a modifier extension, they may interpret the resource incorrectly.
If you’re designing an IG, reach for modifierExtension only when you truly must modify meaning, and document the safety implications clearly.

​
How extensions are defined (where the URL comes from)

Extensions are defined using a StructureDefinition whose type is Extension. That definition typically constrains:
  • allowed context(s) (which resources/elements it can appear on)
  • allowed datatype(s) for value[x] (e.g. only valueCodeableConcept)
  • cardinality and invariants
  • terminology bindings (if coded)
In practice, extension definitions ship in FHIR packages (implementation guides).

​
Interoperability tips

  • Prefer stable, globally unique canonical URLs for extension definitions.
  • If an extension is widely useful, look for an existing standard extension package (HL7, national IGs, etc.) before minting your own.
  • If you need to search by extension content, that’s only possible if the server exposes a SearchParameter for that extension.

​
Next

  • How extensions are introduced and constrained: Profiles
  • How conformance is checked: Validation