This page is part of the FHIR Specification (v0.0.82: DSTU 1). 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

1.12.6.0 Extensibility

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. Applications should not reject resources merely 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 and use extensions, there is a set of requirements that must be met as part of their use and definition.

1.12.6.0.1 Extension Element

Every element in a resource or data type includes an optional "extension" child element that may be present any number of times. The extension elements appear as the first set of children, 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" url="identifies the meaning of the extension (uri)"> 
 <!-- from Element: extension -->
 <value[x]><!-- 0..1 * Value of extension --></value[x]>
</[name]>

Notes:

The url is a mandatory attribute / property and identifies an extension definition in a resource profile that defines the content and meaning of the extension.
The actual content of the extension consists of either a single value in the value[x] element, or it can contain additional extensions, each with their own defining url and content
An extension SHALL have either a value (i.e. a value[x] element) or child extensions. The value[x] element SHALL have content and/or an id attribute that is the target of a reference from the Narrative
When an extension is the target of an internal reference, the reference is always to the value of the extension. An extension is only allowed to be the target of a reference when it has no value[x]
For most extensions, it must be safe for an application processing the content of the resource to ignore an extension. Specifically, this should be understood to mean that the content of the extension does not alter the meaning of the element that contains it. See below for further discussion

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. The value type may be one of the following:

integer
decimal
dateTime
date
instant
string
uri
boolean
code (only if the extension definition provides a fixed binding to a suitable set of codes)
base64Binary
Coding
CodeableConcept
Attachment
Identifier
Quantity
Range
Period
Ratio
HumanName
Address
Contact
Schedule
Resource - a reference to another resource

An extension would contain other extensions instead of a value where the original definition of the extension defines complex content (i.e. the extension has multiple parts rather than a simple data type). If the value of the extension itself needs extending, those 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="http://hl7.org/fhir/Profileiso-21090#name-use" >
    <valueCode value="I" />
  </extension>
  <text value="Chief Red Cloud"/>
</name>

or in JSON:

"name" : {
  "extension: [
    {
      "url" : "http://hl7.org/fhir/Profileiso-21090#name-use",
      "valueCode" : "I"
     }]
  "text": "Chief Red Cloud"/>
}

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 url="http://acme.org/fhir/Profile/main#trial-status" >
    <extension url="http://acme.org/fhir/Profile/main#trial-status-code" >	  
      <valueCode value="unsure" />	  
    </extension>
    <extension url="http://acme.org/fhir/Profile/main#trial-status-date" >	  
      <valueDate value="2009-03-14" />	  
    </extension>
    <extension url="http://acme.org/fhir/Profile/main#trial-status-who" >	  
      <valueResource>	  
        <reference value="Practitioner/example" />	  	    
      </valueResource>	  
    </extension>
  </extension>
  <!-- other data for patient -->
</Patient>

or in JSON:

{
  "resource-type" : "Patient",
  "extension" : [
    {
      "url" : "http://acme.org/fhir/Profile/main#trial-status",
      "extension" : [
        {
          "url" : "http://acme.org/fhir/Profile/main#trial-status-code",
          "valueCode" : "unsure"
        }, 
        {
          "url" : "http://acme.org/fhir/Profile/main#trial-status-date",
          "valueDate" : "2009-03-14"
        }, 
        {
          "url" : "http://acme.org/fhir/Profile/main#trial-status-who",
          "valueResource" : {
            "reference" : "Practitioner/example"
          }
        }
     ]
   }
  ], 
  ... other data for patient... 
}

1.12.6.0.2 Modifier Extensions

There are some cases where the information provided in extensions modifies the meaning of the element that contains it. Typically, this means information that qualifies or negates the primary meaning of the element that contains it. Some examples:

Adding a certainty extension to an Adverse Reaction that includes a value "highly doubtful"
Asserting an additional subsumption relationship on a concept in a value set
An anti-prescription: recording an instruction not to take a medication
Using the Condition resource to record an assertion that a patient doesn't have a particular diagnosis
Asserting that a performer was not actually involved in a Procedure
Recording that a Supply was not provided (i.e. refusal to fill)

Implementers should avoid the use of modifier extensions where possible. Any use should be carefully considered against its possible downstream consequences. However, implementers are often forced into these situations by the business arrangements around the use of resources, so this specification creates a framework for handling these.

If modifier extensions are present, an application cannot safely process the resource unless it knows what the extension means for its own use of the data. This specification allows for such modifier elements to be included at the base of a resource or in any elements that do not have a data type (e.g. the elements that correspond to classes in the resource UML diagrams), using an element named "modifierExtension", which has same content as the extension element documented above.

Implementations processing the data in resources SHALL understand the impact of the extension when using the data. If an application processing the content of a resource does not recognize a modifierExtension and the data from the 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 to inform users that it has not fully understood the source information.

Implementations are not required to "support" the extension in any meaningful way - they may achieve this understanding by rejecting instances that contain this extension. Alternatively, implementations may be able to be sure, due to their implementation environment, that such extensions will never occur. However applications SHOULD always check for extensions irrespective of this.

Note that processing the data of a resource typically means copying or filtering data out of a resource for use in another context (display to a human, decision support, exchange in another format where not all information is included, or storing it for this kind of use). Servers and background processes that simply move whole resources around unchanged are not "processing the data of the resource", and therefore these applications are not required to check for unknown extensions.

1.12.6.0.2.1 Summary: Conformance Rules for Modifier Extensions

A modifierExtension SHALL only modify the element which it contains and/or its children
It SHALL always be safe to show the narrative to humans; any modifier extension SHALL be represented in the narrative.
Applications SHALL always check for modifierExtensions when processing the data from any element that may carry one. If a modifierExtension they do not understand is found, the application SHALL either refuse to process the resource or affected element, or provide an appropriate warning to its users

1.12.6.0.2.2 Example

Example: Because of a lack of clinical consensus, there's no element on Procedure for any expression of certainty around the expression of the Allergy/Intolerance. Some systems mark their entries as "unlikely" or "probable". Applications are allowed to extend a resource with data like this:

<AllergyIntolerance>
  <modifierExtension>
    <url value="http://example.org/fhir/extensions#certainty" />
    <valueCoding>
      <system value="http://example.org/codes/certainty"/>
      <code value="2"/>
      <display value="Unlikely"/>
    </valueCoding>
  </modifierExtension>
  <!-- .. text etc... -->
</AllergyIntolerance>

When an application understands this extension, it means that some developer has provided appropriate instructions for what to do with the data contained in it. Note that there is no obligation that the application do anything at all with the data - it can ignore it if that is safe in its own context, though this would not usually be the case.

When an application that doesn't understand this extension tries to process this resource, it is required to either refuse to process the resource (or containing element), or provide an appropriate warning to its users. Either of these courses of action is potentially difficult. One option is to download the profile that defines the extension (from the given URL), find the name of the extension, and then use the name to display the extension to the user. An error message could look something like this:

Note that the narrative of the resource SHALL contain this qualifying information, so it is safe to show this to the user as an expression of the resource's content. A warning dialog box could be extended to offer the user the choice to see the original narrative.

Here is an example showing a statement that a particular surgeon did not perform an operation:

<Procedure xmlns="http://hl7.org/fhir">
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml">Routine appendicectomy for Fred Smith performed By Susan Taylor. Note: This operation was not performed by Dr Lakin</div>
  </text>
  <!-- ...data... -->
  <performer>
    <modifierExtension>
      <url value="http://example.org/fhir/extensions#didNotPerform"/>
      <valueBoolean value="true"/>
    </modifierExtension>
    <person>
      <reference value="Practitioner/example"/>
      <display value="Dr Lakin"/>
    </person>
  </performer>
  <!-- ...data... -->
</Procedure>

In this case, if an application is not reading the performers of the operation at all, the fact that one of the performers has a modifierExtension is irrelevant and the application is free to ignore it.

1.12.6.0.2.3 Special Case: Missing data

In some cases, implementers may find that they do not have appropriate data for an element with minimum cardinality = 1. In this case, the element must be present, but unless the resource or a profile on it has made the actual value of the primitive data type mandatory, it is possible to provide an extension that explains why the primitive value is not present:

<uri>
  <extension url="http://hl7.org/fhir/Profile/general-extensions#data-absent-reason">
    <valueCode="unknown"/>
  </extension>
</uri>

In this example, instead of a value, a data missing code is provided. Note that it is not required that this particular extension be used. This extension is not a modifier extension, because the primitive data type has no value.

It is not valid to create a fictional piece of data for the primitive value, and then to add an extension indicating that the data has been constructed to meet the data rules. This would be both a bad idea, and also a modifier extension, which is not allowed on data types.

1.12.6.0.3 Exchanging Extensions

Extensions are a way of allowing local requirements to be reflected in a resource using a common information based approach so that all systems can confidently process them using the same tools. However, when it comes to processing the information, applications will be constrained in their ability to handle extensions by the degree to which they are informed about them.

While the structured definition of an extension should always be available (see below for details), the mere availability of a definition does not automatically mean that applications know how to handle them correctly - generally, human decisions are required to made around how the data extensions contain should be handled, along with the implicit obligations that around the information.

For this reason, local requirements that manifest as extensions are an obstacle to integration. The more the requirements are shared (i.e. regional or national scale), the less impact they will have. The consistent representation, definition and registration of extensions that this specification defines cannot resolve that problem - it only provides a framework within which such local variations can be handled more easily.

When it comes to deploying applications that support local requirements, situations will very likely arise where different applications exchanging information with each other are supporting different sets of extensions. This specification makes some basic rules that are intended to make management of these situations easier, but they cannot resolve them.

When exchanging resources, systems SHOULD retain unknown extensions when they are capable of doing so (just as they SHOULD retain core elements when they are capable of doing so)
If a system modifies a resource it SHOULD remove any extensions that it does not understand from the modified element and its descendants, because it cannot know whether the modifications it has made might invalidate the value of the unknown extension
Systems that drop existing elements are considered to be "processing the resource"
A system SHALL not modify a resource or element that contains "modifier" extensions it doesn't understand
Applications SHOULD ignore extensions that they do not recognize if they are not "modifier" extensions
Systems that do not accept unknown extensions SHALL declare so in their Conformance resource instances

The degree to which a system can retain unknown extensions is a function of the type of system it is: a general purpose FHIR server, or a middleware engine would be expected to retain all extensions, while an application that manages patient registration through a user interface can only retain extensions to the degree that the information in them is part of the set managed by the user. Other applications will fall somewhere between these two extremes.

1.12.6.0.3.1 Summary: Handling extensions

Use the following rules as a guideline for handling resources:

When writing extensions, make sure they are defined and published
When reading, navigating through or searching on elements that can have modifier extensions, check whether there are any
When reading elements, ignore other extensions, unless you want to read a particular extension
Retain extensions whenever you can

1.12.6.0.4 Defining Extensions

Extensions may be defined by any project or jurisdiction, up to and including international standards organizations such as HL7 itself. Extensions are defined and 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:

Field	Required?	Path in Profile (from Profile.extensionDefn)	Description
Code	Required	.code	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	.contextType and .context	The context of this extension. See above. The context has two parts: a type, and a path which supplies the details
Short Definition	Required	.definition.short	A brief description of the extension used in the XML descriptions when the extension is referenced in a profile
Definition	Required	.definition.formal	A formal statement of the meaning of the content of the field
Requirements	Optional	.definition.requirements	Identifies the reason the extension is needed
Comments	Optional	.definition.comments	Additional other information about the extension, including information such as use notes
Cardinality	Required	.definition.min / .definition.max	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	.definition.type	The type(s) of the extension. This SHALL be a valid FHIR data type as described above, or empty, if the extension will contain other extensions
XPaths	Optional	.definition.constraint	One or more XPath statements that SHALL evaluate to true when the extension is used
Is Modifier	Required	.definition.isModifier	Whether the extension changes the meaning or interpretation of the element containing the extension (or any descendant of that element). Extensions defined as IsModifier=true are always represented in modifierExtension elements, and extensions defined as IsModifier=false are always represented in Extension elements
RIM Mapping	Conditional	.definition.mapping...	The formal mapping from this extension to the RIM. Required for HL7-defined extensions that apply to resources with RIM mappings, but optional in other contexts
v2 Mapping	Optional	.definition.mapping...	Mapping to a v2 segment/field/etc., if desired and appropriate.
Binding	Conditional	.definition.binding	For the types CodeableConcept and Coding. See Terminologies

Notes:

Mappings are not required to be computable (i.e. executable logic). Mappings to other specifications can also be provided.

Whenever resources containing extensions are exchanged, the definitions of the extensions SHALL 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.

1.12.6.0.5 Control of extensions

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 does not define "modifier" extensions - if HL7 publishes an element that modifies the meaning of other elements, 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 SHALL 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 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 or other publicly accessible 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 once that resource is normative.

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

On This Page:

Extensibility

isModifier

Defining Extensions