. Page versions: R5 R4B R4 R3 R2This page is part of the FHIR Specification (v0.11: DSTU 1 Ballot 3). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2
See also Extensibility Examples as well.
This exchange specification is based on generally agreed common requirements across healthcare - covering many jurisdictions, domains, and different functional approaches. As such, it is common for specific implementations to have valid requirements that will not be directly included in this specification. Incorporating all of these requirements would make this specification very cumbersome and difficult to implement. Instead, this specification expects that these additional distinct requirements will be implemented as extensions.
As such, extensibility is a fundamental part of the design of this specification. Every element in a resource may have extension child elements to represent additional information that is not part of the basic definition of the resource. Conformant applications are not allowed to reject resources because they contain extensions, though they may need to reject resources because of the specific contents of the extensions.
Note that, unlike in many other specifications, there can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core simplicity for everyone.
In order to make the use of extensions safe and manageable, there is a strict governance applied to the definition and use of extensions. Though any implementer is allowed to define an extension, there is a set of requirements that must be met as part of the definition of the extension.
Every element in a resource includes an optional "extension" element that may be present any number of times in the element. The extension element appears as the first child, prior to any other defined child elements. This is the content model of the extension as it appears in each resource:
<[name] xmlns="http://hl7.org/fhir"> <!-- from Element: extension --> <url value="[uri]"/><!-- 1..1 identifies the meaning of the extension --> <isModifier value="[boolean]"/><!-- 0..1 If extension modifies other elements/extensions --> <value[x]><!-- 0..1 * Value of extension --></value[x]> </[name]>
Notes:
The value[x] element has the [x] replaced with the title-cased name of one of the defined types, and the contents as defined for that type, or another extension. The value type may be one of the following:
Nested extensions are used where the original definition of the extension defines complex content (i.e. multiple parts of the extension, not a simple data type). If the value of the extension themselves need extending, these extensions go in the content of the value[x] element.
Here is an example of a name with a simple extension for a tribal name:
<name>
<extension>
<url value="http://hl7.org/fhir/profile/@iso-21090#name-use" />
<valueCode value="I" />
</extension>
<text value="Chief Red Cloud"/>
</name>
The proper use of the URL value is discussed below.
Extending a patient with an opt-in status for a clinical trial, with 3 fields: status, date of recording, and person who recorded:
<Patient>
<extension>
<extension>
<url value="http://acme.org/fhir/profiles/@main#trial-status-code" />
<valueCode value="unsure" />
</extension>
<extension>
<url value="http://acme.org/fhir/profiles/@main#trial-status-date" />
<valueDate value="2009-03-14" />
</extension>
<extension>
<url value="http://acme.org/fhir/profiles/@main#trial-status-who" />
<valueResource>
<type value="Practitioner" />
<reference value="practitioner/@example" />
</valueResource>
</extension>
<url value="http://acme.org/fhir/profiles/@main#trial-status" />
</extension>
<!-- other data for patient -->
</Patient>
Note that extensions come first in the extension, prior to the url element.
As well as providing additional information, extensions may be used to modify the meaning of other existing elements or even to negate their meanings. As an example, an implementation may wish to add a "certainty" extension to the AllergyIntolerance to indicate that some allergies are only suspected. If the extension had a value of "highly doubtful", then it would change the understanding of the allergy/intolerance, and implementations should not ignore this. Modifying the meaning of other elements makes these particular extensions unsafe to ignore, and so this must be explicitly labelled in the instance.
If the application processing the content of a resource does not recognize an extension that is labeled "IsModifier", and the data from element it extends is processed by the application, the application SHALL either refuse to process the data, or carry a warning concerning the data along with any action or output that results from processing the data.
Here is an Australian example where for cultural reasons, certain names that have been used previously must never be mentioned again:
<name>
<extension>
<url value="http://hl7.org/fhir/profile/@iso-21090#name-use" />
<isModifier value="true" />
<valueCode value="DN" />
</extension>
<text value="Arinyoo"/>
</name>
Because the intent of the name use code is that this name should not actually be used as if it were the patient's name, the extension is labelled "isModifier" = it is not safe to use this name unless you understand the extension.
Servers and background processes that move resources around are not "processing the data of the resource", and these applications are not required to check for unknown extensions. Any process that copies data out of a resource for use in another context (display to a human, decision support, exchange in another format that doesn't support extensions) is processing the data.
Note that it must always be safe to show the narrative to humans; any extension that is labeled as "IsModifier" must be represented in the narrative. Applications are required to ignore extensions that they do not recognize if their "isModifier" element is missing or set to false.
Extensions may be defined by any project or jurisdiction, up to and including international standards organizations such as HL7 itself, and are published as part of a Resource Profile. Extensions are always defined against some particular context - the type of element that they may be used to extend. The following are possible contexts for an extension:
| Context type | Context format | Examples |
|---|---|---|
| A particular element (including the root) in a single resource | The element path for that element | Profile.resource.element; Person |
| A particular element (including the root) in a particular data type | The data type name for primitive types or the element path for complex data types | Address.part.value; string |
| A particular context in one of the mapped reference models | The name of the reference model followed by the mapping path | RIM: Act[moodCode="EVN"] |
| Another extension | The profile uri of the extension followed by the extension code | http://myextensions.org#someExtension |
| A set of some combination of the above | As above, separated by ';' | Address; Contact |
In addition, an extension definition might apply additional constraints with regards to particular element values of the target that make its use appropriate. Extensions SHALL only be used on a target for which they are defined.
Each extension is defined using the following fields:
| Code | Required | The name that is used as a code in a resource to identify this extension - unique in the context of the defining profile |
| Context | Required | The context of this extension. See above. The context has two parts: a type, and a path which supplies the details |
| Short Defn | Required | A brief description of the extension used in the XML descriptions when the extension is referenced in a profile |
| Definition | Required | A formal statement of the meaning of the content of the field |
| Requirements | Optional | Identifies the reason the extension is needed |
| Comments | Optional | Additional other information about the extension, including information such as use notes |
| Cardinality | Required | The cardinality of this extension. Specifying a minimum cardinality of 1 means that if the source system declares that it conforms to an extension that declares a type including this extension, this extension must be included in the resource. Cardinality can be constrained but not loosened in profiles that reference this extension |
| Type | Required | The type(s) of the extension. This must be a valid FHIR data type as described above, or "Extension: x,y,z" which indicates that the extension codes x,y, and z will be contained in the extension |
| XPaths | Optional | One or more XPath statements that must evaluate to true when the extension is used |
| Must Understand | Required | Whether the extension must be understood by any system reading the resource. There are 3 possible values: "true" - the extension must be understood, "false" - the extension does not need to be understood, and "sender" - the sender can decide whether the extension needs to be understood |
| RIM Mapping | Conditional | The formal mapping from this extension to the RIM. Required for HL7-defined extensions that apply to resources with RIM mappings, but may be optional in other contexts |
| v2 Mapping | Optional | Mapping to a v2 segment/field/etc., if desired and appropriate. |
| Binding | Conditional | For the types CodeableConcept and Coding. See Terminologies |
Notes:
Whenever resources containing extensions are exchanged, the definitions of the extensions must be available to all the parties that share the resources. Each extension contains a URI that references the source of the definitions as a Resource Profile. The source SHOULD be a literal reference, such as an http: url that refers to an end-point that responds with the contents of the definitions - preferably a FHIR RESTful server supporting the Resources Profile, or a logical reference (e.g. using a urn:) - for instance, to a national published standard.
As well as defining the base element structure for resources, HL7 also publishes extensions. HL7 publishes data definitions as extensions rather than as part of the base resource structure in order to keep the base resource structure simple and concise, and to allow implementers not to engage with an entire world's worth of functionality up front. Note that HL7 extensions are never flagged as must-understand - if HL7 publishes resource content that must be understood, it will be part of the resource content itself, since everyone has to understand the extension anyway.
Before extensions can be used in instances, they must be published. HL7 maintains two extension registries, and users are encouraged to register their extensions there. But this is not required; all that is required is that the extension is published in a context that is available for users of the extension. So, for example, if a particular extension is used exchanged within a single institution, the definition of the extension can be placed on the institution's intranet. However since, by their nature, resources tend to travel well, it's always better to use the HL7 extension registries.
HL7 provides two extension registries. The first is for HL7 approved extensions. These have been approved by an appropriate part of the HL7 community following a review process, and have formal standing. The other registry is provided as a service to the community, and anyone can register an extension on it.
| Registry | Search | Submit |
|---|---|---|
| HL7 Approved | [TBD] | [TBD] |
| Community | [TBD] | [TBD] |
| Interim | http://hl7connect.healthintersections.com.au/svc/fhir/profile/search | http://hl7connect.healthintersections.com.au/svc/fhir/profile/upload |
HL7 profiles defining extensions may be balloted alongside resource content as part of the FHIR specification or may be published as part of separate specifications. When HL7 publishes extensions as part of the FHIR specification, these extensions SHALL be used for this data whenever the data is represented in instances. Applications SHOULD use other HL7-defined extensions published to represent equivalent data in the interest of maximum interoperability. If referencing a profile that defines extensions, implementations declaring conformance with the profile SHALL use the profile-defined and imported extensions when conveying equivalent data elements.
To minimize complexity for implementers, HL7 will not elevate content defined in an HL7-approved extension to be content defined in a core resource in future versions of the resource.
In some cases, an HL7 work group or other body may publish a profile whose sole purpose is to define extensions expected to be needed by implementers in a particular context. E.g. extensions needed to map a particular set of v2 segments or a v3 model.
Implementations are encouraged to share their extensions with HL7 and register them with the HL7 extension registry. The domain committees will work to elevate the extensions into HL7 published extensions or, if adopted by a broad enough portion of the implementer community, the into the base resource structure itself.
To avoid interoperability issues, extensions SHALL NOT change their definition once published. (Small clarifications to descriptions that do not affect interoperability are permitted.) Rather than modifying an existing extension, a new extension should be introduced. Revisions to an extension may extend the set of contexts in which the extension apply but may not remove or constrain any context previously listed