FHIR Extension

Every extension is defined by a canonical URL that uniquely identifies it globally. The extension itself contains a fixed structure: a url (identifying the extension definition) and a value[x] (the actual data). Extensions can be simple (a single data element) or complex (containing nested extensions). This strict structure allows any FHIR parser to safely handle unknown extensions without failing.

• Canonical URL: Globally unique identifier (e.g., http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName)
• Value[x]: The payload, which can be any valid FHIR data type
• Modifier Extensions: A special subclass that changes the meaning of surrounding elements, requiring careful handling

Extensions are designed so that a system unaware of a specific extension can still safely process the resource. The base FHIR specification mandates that receivers must not reject resources solely because they contain unrecognized extensions. This rule is the cornerstone of FHIR's forward-compatibility. However, modifier extensions are an exception—if a receiver cannot process a modifier extension, it must treat the containing element's data as unreliable.

• Must-Support Flag: Profiles can mark extensions as mustSupport, requiring conformant systems to process them
• Is-Modifier Flag: When true, the extension alters the interpretation of the element it extends, and unknown modifiers render the parent element unsafe to use

An extension definition explicitly declares where it can be applied using a context element. This prevents extensions from being attached to inappropriate resources or elements. The context can target a specific resource type, a data type, a path within a resource, or a profile. This governance mechanism ensures extensions are used predictably and validators can enforce their correct placement.

• Context Type: resource, datatype, extension, or fhirpath
• Context Expression: A precise FHIRPath expression defining valid attachment points
• Cardinality Constraints: Defines whether the extension can appear zero or one times (0..1) or multiple times (0..*)

Extensions become normative through FHIR Profiles and Implementation Guides. A profile constrains a base resource and can mandate the presence of specific extensions using slicing on the extension array. Implementation guides package these profiles with documentation, ValueSets, and examples to create a complete, enforceable specification for a domain like US Core or Da Vinci.

• Slicing: Discriminates extensions by their canonical URL to enforce specific extension usage
• Obligation Codes: In newer FHIR versions, profiles can assign obligations (e.g., SHALL:populate) to extensions
• Packaged Distribution: Implementation guides bundle extensions with all dependencies for consistent deployment

HL7 maintains a registry of core extensions that address common, cross-domain needs (e.g., patient-birthTime, data-absent-reason). These are defined alongside the base specification and carry the http://hl7.org/fhir/StructureDefinition/ namespace. Community extensions are authored by implementers for domain-specific needs and use their own canonical URLs. Before creating a new extension, implementers are strongly encouraged to search the registry to avoid duplication.

• Core Registry: Curated by HL7, reusable across implementations
• Community Namespace: Must be under the implementer's control to guarantee uniqueness
• Registration: HL7 provides a public registry for community extensions to promote reuse

Extensions carry metadata that instructs systems on how to display them to human users. The Extension.definition element references a StructureDefinition that includes a short label, a definition description, and a comment field. FHIR servers and clinical viewers use this metadata to render extension values meaningfully in the human-readable narrative of a resource, ensuring that custom data is not hidden from clinicians.

• Short Label: A concise, human-readable name for UI display
• Definition Field: A full explanation of the extension's purpose
• Example Values: StructureDefinitions can include sample values to guide implementers