This page is part of the FHIR Specification (v0.4.0: DSTU 2 Draft). 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.20.0 Extensibility

This exchange specification is based on generally agreed common requirements across healthcare - covering many jurisdictions, domains, and different functional approaches. It is common for specific implementations to have valid requirements that are not part of these agreed common requirements. 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.20.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. This is the content model of the extension as it appears in each resource:

Structure
UML
XML
JSON
All

Structure

Name	Card.	Type	Description & Constraints
Extension	1..1	Element
url	1..1	uri	identifies the meaning of the extension
value[x]	0..1	*	Value of extension

UML Diagram

to do

XML Template

<extension|modifierExtension 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]>
</extension|modifierExtension>

JSON Template


  // from Element: extension
  "<url>" : { // identifies the meaning of the extension
    // value[x]: Value of extension. One of these 23:
    "valueInteger" : <integer>
    "valueDecimal" : <decimal>
    "valueDateTime" : "<dateTime>"
    "valueDate" : "<date>"
    "valueInstant" : "<instant>"
    "valueString" : "<string>"
    "valueUri" : "<uri>"
    "valueBoolean" : <boolean>
    "valueCode" : "<code>"
    "valueBase64Binary" : "<base64Binary>"
    "valueCoding" : { Coding }
    "valueCodeableConcept" : { CodeableConcept }
    "valueAttachment" : { Attachment }
    "valueIdentifier" : { Identifier }
    "valueQuantity" : { Quantity }
    "valueRange" : { Range }
    "valuePeriod" : { Period }
    "valueRatio" : { Ratio }
    "valueHumanName" : { HumanName }
    "valueAddress" : { Address }
    "valueContact" : { Contact }
    "valueSchedule" : { Schedule }
    "valueReference" : { Reference }
  }
}

Structure

Name	Card.	Type	Description & Constraints
Extension	1..1	Element
url	1..1	uri	identifies the meaning of the extension
value[x]	0..1	*	Value of extension

UML Diagram

todo

XML Template

<extension|modifierExtension 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]>
</extension|modifierExtension>

JSON Template


  // from Element: extension
  "<url>" : { // identifies the meaning of the extension
    // value[x]: Value of extension. One of these 23:
    "valueInteger" : <integer>
    "valueDecimal" : <decimal>
    "valueDateTime" : "<dateTime>"
    "valueDate" : "<date>"
    "valueInstant" : "<instant>"
    "valueString" : "<string>"
    "valueUri" : "<uri>"
    "valueBoolean" : <boolean>
    "valueCode" : "<code>"
    "valueBase64Binary" : "<base64Binary>"
    "valueCoding" : { Coding }
    "valueCodeableConcept" : { CodeableConcept }
    "valueAttachment" : { Attachment }
    "valueIdentifier" : { Identifier }
    "valueQuantity" : { Quantity }
    "valueRange" : { Range }
    "valuePeriod" : { Period }
    "valueRatio" : { Ratio }
    "valueHumanName" : { HumanName }
    "valueAddress" : { Address }
    "valueContact" : { Contact }
    "valueSchedule" : { Schedule }
    "valueReference" : { Reference }
  }
}

Notes:

The url is a mandatory attribute / property and identifies a retrievable extension definition that defines the content and meaning of the extension.
An extension SHALL have either a value (i.e. a [x] element) or sub-extensions. If present, the [x] element SHALL have content (value attribute or other elements)
If it is not safe for an application processing the content of the resource to ignore the extension it must be represented diffferent (see below)
The value[x] element has an actual name of "value" and then the TitleCased name of one of these defined types, and it's contents are those as defined for that type:
- 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
- ContactPoint
- Timing
- Signature
- Reference - a reference to another resource

Here is an example of an extension in XML:

<name>
  <extension url="http://hl7.org/fhir/ExtensionDefinition/iso-21090-name-use" >
    <valueCode value="I" />
  </extension>
  <text value="Chief Red Cloud"/>
</name>

In JSON, extensions are represented similarly:

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

Making the types explicit in the representation means that all systems can read and write (and therefore store and/or exchange) extensions correctly without needing to access the definition of the extension.

Extensions can also contain extensions, either because the extension definition itself defines complex content, or because the extension is extended with an additional extension defined separately.

In the first case, the identity of the parts of the extension are local/relative to the reference to the extension definition.

As an example, consider extending a patient with an opt-in status for a clinical trial, with 3 fields: status, date of recording, and the person who enrolled them (see definition). In XML:

<Patient>
  <extension url="http://acme.org/fhir/ExtensionDefinition/trial-status" >
    <extension url="code" >	  
      <valueCode value="unsure" />	  
    </extension>
    <extension url="date" >	  
      <valueDate value="2009-03-14" />	  
    </extension>
    <extension url="registrar" >	  
      <valueReference>	  
        <reference value="Practitioner/example" />	  	    
      </valueReference>	  
    </extension>
  </extension>
  <!-- other data for patient -->
</Patient>

Or in JSON:

{
  "resourceType" : "Patient",
  "extension" : [{
    "url" : "http://acme.org/fhir/ExtensionDefinition/trial-status",
    "extension" : [{ 
      "url" : "code",
      "valueCode" : "unsure"
    }, {
      "url" : "date", 
      "valueDate" : "2009-03-14" 
    },  {
      "url" : "registrar",
      "valueReference" : {
        "reference" : "Practitioner/example"
       }
    }]
  }]
  ... other data for patient ...
}

The JSON representation is more concise, since it is not constrained by the limitations of schema, though the type of the value must still be explicit.

In the second case, the contained extension is defined separately.

The registrar was defined as a separate extension (e.g. to allow wider use). The url of the extension is different:

<Patient>
  <extension url="http://acme.org/fhir/ExtensionDefinition/trial-status" >
    <extension url="code" >	  
      <valueCode value="unsure" />	  
    </extension>
    <extension url="date" >	  
      <valueDate value="2009-03-14" />	  
    </extension>
    <extension url="http://acme.org/fhir/ExtensionDefinition/registrar" >	  
      <valueReference array="true">	  
        <reference value="Practitioner/example" />	  	    
      </valueReference>	  
    </extension>
  </extension>
  <!-- other data for patient -->
</Patient>

or in JSON:

{
  "resourceType" : "Patient",
  "extension" : [{
    "url" : "http://acme.org/fhir/ExtensionDefinition/trial-status",
    "extension" : [{
      "url" : "code",
      "valueCode" : "unsure"
    }, {
      "url" : "date",
      "valueDate" : "2009-03-14" 
    }, {
      "url" : "http://acme.org/fhir/ExtensionDefinition/registrar",
      "valueReference" : {
        "reference" : "Practitioner/example"
      }
    }]
  }]
  ... other data for patient ...
}

1.20.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 Allergy/Intolerance 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 cases. 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). Elements that are data types, or that are inside data types SHALL NOT have modifier extensions.

In XML, these modifier elements are represented using an element named "modifierExtension", which has same content as the extension element documented above:

Example: There's no element on Procedure so it can be used to say "this procedure did not occur"; however, a source system does have this flag on it's procedure records. It could choose not to share those procedures (e.g. consider them as logically deleted). However, it may be that it is required to share procedures marked as "did not occur" with it's trading partners. Hence, applications are allowed to extend a resource with data like this:

<Procedure>
  <modifierExtension url="http://example.org/fhir/ExtensionDefinition/negation">
    <valueBoolean value="true"/>
  </modifierExtension>
  <!-- ... other content ... -->
</Procedure>

Or in JSON:

{
  "resourceType" : "Procedure",
  "modifierExtension" : [{ 
    "url" : "http://example.org/fhir/ExtensionDefinition/negation",
    "valueBoolean" : "true"
  }],
  .. other content ... 
}

Implementations processing the data in resources SHALL check for modifiers anywhere they may appear, and if a modifier extension is present, SHALL do one of these things:

understand the impact of the extension when using the data
refuse to process the data
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

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 modifier extensions.

#1: 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 because of the existence of the modifier extension.

#2: This means that implementations are not inherently required to "support" a modifier extension in any meaningful way - they may achieve this understanding by rejecting instances that contain this extension. Applications may also be able to ignore a modifier extension if that can know that this is safe to do in its own context, though this would not usually be the case.

Note that implementations may be able to be sure, due to their implementation environment (e.g. specific trading partner agreement), that modifier extensions will never occur, and can therefore meet the requirement to check for modifiers at the design stage. However, since integration and deployment options often change subsequently, applications SHOULD always check for modifier extensions when processing resources anyway.

#3: One way to warn the user is to download the extension definition from the given URL, and then use the defined display name to present 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 the procedure example from above with narrative:

<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="http://example.org/fhir/ExtensionDefinition/negation">
      <boolean 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. If it does process the performers, and it sees the modifier extension, it can warn the user that there is data it does not understand, and present the narrative to the user.

1.20.0.2.1 Summary: Conformance Rules for Modifier Extensions

Modifier Extensions SHALL only modify the element which contains it and/or that element's 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 modifier extensions when processing the data from any element that may carry one
If a modifier Extension they do not understand is present, the application SHALL either refuse to process the resource or affected element, or provide an appropriate warning to its users

1.20.0.2.2 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/ExtensionDefinition/data-absent-reason">
    <code="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.20.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.20.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