. Page versions: R5 R4B R4 R3 R2This page is part of the FHIR Specification (v0.06: DSTU 1 Ballot 2). 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
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 resource includes an extension section that may be used 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.
Each resource includes the optional "extension" element that may be present any number of times before the narrative element at the end of the resource. This is the content model of the extension as it appears in each resource:
<[name] xmlns="http://hl7.org/fhir"> <url><!-- 1..1 uri identifies the meaning of the extension --></url> <ref><!-- 0..1 idref Internal reference to context of the extension (xml:id) --></ref> <mustUnderstand><!-- 0..1 boolean Must you recognize this extension to safely read the resource? --></mustUnderstand> <value[x]><!-- 0..1 Value of extension --></value[x]> <extension><!-- 0..* Extension Nested Extensions --></extension> </[name]>
Notes:
The value[x] element has the [x] replaced with the 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:
Some of the primitive data types are not included in this list. Extensions that might wish to use one of the omitted primitives are expected to use one of the more complex types in their place. For example, decimal and integer are handed by Quantity, base64Binary by Attachment, etc.
Nested extensions cannot have a ref element. The [type] element is optional unless the definitions of the extension codes make rules about it. Extensions can never have a default value.
As well as providing additional information, extensions may be used to qualify the meaning of other existing elements or even to negate their meanings. This behavior makes these particular extensions unsafe to ignore. Such extensions must have an attribute mustUnderstand = true.
Any application processing the data of a resource must check for extensions labeled "mustUnderstand".
If the application does not recognize the code on an extension that is labeled "mustUnderstand", and where the extension either has no internal reference, or it references data 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.
Note that it must always be safe to show the narrative to humans; any extension that is labeled as "mustUnderstand" must be represented in the narrative. Applications are required to ignore extensions that they do not recognize if their "mustUnderstand" element is missing or set to false.
Extensions labeled "mustUnderstand" SHALL be attached to reference points within an instance such that all data elements whose meaning may be impacted by the extension are contained within the element to which the extension is attached.
Note that servers and background process 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.
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 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 b 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
This is an old version of FHIR retained for archive purposes. Do not use for anything else
Implementers are welcome to experiment with the content defined here, but should note that the contents are subject to change without prior notice.
© HL7.org 2011 - 2012. FHIR v0.06 generated on Tue, Dec 4, 2012 00:04+1100. License