← ReferenceStandards

What is an Extension?

An Extension adds a data element to a FHIR resource that is not part of the base specification. Extensions are the formal mechanism for adding country-specific, institution-specific, or use-case-specific data without forking the standard.

Every FHIR element supports extensions. An extension on a Patient might record birth place, ethnic origin, or a national insurance number system not covered by the base identifier element.

Extension on a Patient (birthPlace)

{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/patient-birthPlace",
      "valueAddress": {
        "city": "Košice",
        "country": "SK"
      }
    }
  ],
  "name": [{ "family": "Horváth", "given": ["Jana"] }]
}

Rules for extensions

url: Every extension must have a URL — a globally unique identifier pointing to its StructureDefinition. The URL is the contract.
value[x]: Simple extensions carry a value — valueString, valueBoolean, valueQuantity, valueCodeableConcept, valueAddress, etc.
Complex extensions: Extensions with nested sub-extensions instead of a single value. Used when multiple related fields need to be grouped.
modifierExtension: An extension that changes the meaning of the resource — e.g. marks data as "do not use". Receivers that do not understand a modifierExtension must reject the resource.