STU 3 Ballot

This page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). 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

2.20.0 Extensibility

FHIR Infrastructure Work GroupMaturity Level: 3Ballot Status: STU 3

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.

2.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

NameFlagsCard.TypeDescription & Constraintsdoco
.. Extension IElement
Must have either extensions or value[x], not both
... url 1..1uriidentifies the meaning of the extension
... value[x] 0..1*Value of extension

doco Documentation for this format

XML Template

<extension|modifierExtension xmlns="http://hl7.org/fhir" url="identifies the meaning of the extension (uri)"> doco
 <!-- from Element: extension -->
 <value[x]><!-- 0..1 * Value of extension --></value[x]>
</extension|modifierExtension>

Turtle Template

 
@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:Extension.url [ uri ]; # 1..1 identifies the meaning of the extension
  # Extension.value[x] : 0..1 Value of extension. One of these 38
    fhir:Extension.valueBase64Binary [ base64Binary ]
    fhir:Extension.valueBoolean [ boolean ]
    fhir:Extension.valueCode [ code ]
    fhir:Extension.valueDate [ date ]
    fhir:Extension.valueDateTime [ dateTime ]
    fhir:Extension.valueDecimal [ decimal ]
    fhir:Extension.valueId [ id ]
    fhir:Extension.valueInstant [ instant ]
    fhir:Extension.valueInteger [ integer ]
    fhir:Extension.valueMarkdown [ markdown ]
    fhir:Extension.valueOid [ oid ]
    fhir:Extension.valuePositiveInt [ positiveInt ]
    fhir:Extension.valueString [ string ]
    fhir:Extension.valueTime [ time ]
    fhir:Extension.valueUnsignedInt [ unsignedInt ]
    fhir:Extension.valueUri [ uri ]
    fhir:Extension.valueAddress [ Address ]
    fhir:Extension.valueAge [ Age ]
    fhir:Extension.valueAnnotation [ Annotation ]
    fhir:Extension.valueAttachment [ Attachment ]
    fhir:Extension.valueCodeableConcept [ CodeableConcept ]
    fhir:Extension.valueCoding [ Coding ]
    fhir:Extension.valueContactPoint [ ContactPoint ]
    fhir:Extension.valueCount [ Count ]
    fhir:Extension.valueDistance [ Distance ]
    fhir:Extension.valueDuration [ Duration ]
    fhir:Extension.valueHumanName [ HumanName ]
    fhir:Extension.valueIdentifier [ Identifier ]
    fhir:Extension.valueMoney [ Money ]
    fhir:Extension.valuePeriod [ Period ]
    fhir:Extension.valueQuantity [ Quantity ]
    fhir:Extension.valueRange [ Range ]
    fhir:Extension.valueRatio [ Ratio ]
    fhir:Extension.valueReference [ Reference ]
    fhir:Extension.valueSampledData [ SampledData ]
    fhir:Extension.valueSignature [ Signature ]
    fhir:Extension.valueTiming [ Timing ]
    fhir:Extension.valueMeta [ Meta ]
]

Changes since DSTU2


Extension
Extension.value[x] Add Age, Add Count, Add Distance, Add Duration, Add Money

See the Full Difference for further information

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Extension IElement
Must have either extensions or value[x], not both
... url 1..1uriidentifies the meaning of the extension
... value[x] 0..1*Value of extension

doco Documentation for this format

XML Template

<extension|modifierExtension xmlns="http://hl7.org/fhir" url="identifies the meaning of the extension (uri)"> doco
 <!-- from Element: extension -->
 <value[x]><!-- 0..1 * Value of extension --></value[x]>
</extension|modifierExtension>

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .

[
 # from Element: Element.extension
  fhir:Extension.url [ uri ]; # 1..1 identifies the meaning of the extension
  # Extension.value[x] : 0..1 Value of extension. One of these 38
    fhir:Extension.valueBase64Binary [ base64Binary ]
    fhir:Extension.valueBoolean [ boolean ]
    fhir:Extension.valueCode [ code ]
    fhir:Extension.valueDate [ date ]
    fhir:Extension.valueDateTime [ dateTime ]
    fhir:Extension.valueDecimal [ decimal ]
    fhir:Extension.valueId [ id ]
    fhir:Extension.valueInstant [ instant ]
    fhir:Extension.valueInteger [ integer ]
    fhir:Extension.valueMarkdown [ markdown ]
    fhir:Extension.valueOid [ oid ]
    fhir:Extension.valuePositiveInt [ positiveInt ]
    fhir:Extension.valueString [ string ]
    fhir:Extension.valueTime [ time ]
    fhir:Extension.valueUnsignedInt [ unsignedInt ]
    fhir:Extension.valueUri [ uri ]
    fhir:Extension.valueAddress [ Address ]
    fhir:Extension.valueAge [ Age ]
    fhir:Extension.valueAnnotation [ Annotation ]
    fhir:Extension.valueAttachment [ Attachment ]
    fhir:Extension.valueCodeableConcept [ CodeableConcept ]
    fhir:Extension.valueCoding [ Coding ]
    fhir:Extension.valueContactPoint [ ContactPoint ]
    fhir:Extension.valueCount [ Count ]
    fhir:Extension.valueDistance [ Distance ]
    fhir:Extension.valueDuration [ Duration ]
    fhir:Extension.valueHumanName [ HumanName ]
    fhir:Extension.valueIdentifier [ Identifier ]
    fhir:Extension.valueMoney [ Money ]
    fhir:Extension.valuePeriod [ Period ]
    fhir:Extension.valueQuantity [ Quantity ]
    fhir:Extension.valueRange [ Range ]
    fhir:Extension.valueRatio [ Ratio ]
    fhir:Extension.valueReference [ Reference ]
    fhir:Extension.valueSampledData [ SampledData ]
    fhir:Extension.valueSignature [ Signature ]
    fhir:Extension.valueTiming [ Timing ]
    fhir:Extension.valueMeta [ Meta ]
]

Changes since DSTU2

Extension
Extension.value[x] Add Age, Add Count, Add Distance, Add Duration, Add Money

See the Full Difference for further information

Notes:

  • The url is a mandatory attribute / property and identifies a retrievable extension definition that defines the content and meaning of the extension
  • The url SHALL be a URL, not a URN (e.g. not an OID or a UUID), and it SHALL be the canonical URL of a StructureDefinition that defines the extension. Except for child extensions defined within a complex extensions, the URL SHALL be an absolute URL). The StructureDefinition the defines the extension SHOULD be available at the identified location so that resource processors can access the definition from the URL
  • An extension SHALL have either a value (i.e. a value[x] element) or sub-extensions, but not both. If present, the value[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 diffferently, using a Modifier Extension
  • The value[x] element has an actual name of "value" and then the TitleCased name of one of these defined types, and its contents are those as defined for that type:

Here is an example of an extension in XML: 

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

In this example, the name with text = "Chief Red Cloud" is extended to have a name use code of "Indigenous" (defined in ISO 21090, but very rarely used in practice).

In JSON, extensions are represented similarly: 

  "name" : {
    "extension" : [{
      "url" : "http://hl7.org/fhir/StructureDefinition/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.

Note that the JSON represenation for extensions on primitive data types is handled differently. See Representing primitive types in JSON for further information.

Extensions can also contain extensions, either because the extension definition itself defines complex content - that is, a nested tree of values in the extension, 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: clinical trial number, period of involvement, and a reason for enrollment. In XML: 

<Patient>
  <extension url="http://hl7.org/fhir/StructureDefinition/patient-clinicalTrial" >
    <extension url="NCT" >
      <valueString value="123456789" />
    </extension>
    <extension url="period" >	  
      <valuePeriod>
        <start value="2009-03-14" />	  
      </valuePeriod>
    </extension>
    <extension url="reason" >	  
      <valueCodeableConcept>	  
        <coding>	  	    
          <system value="http://acme.org/codes/general" />	  
          <code value="tt14j" />	  
        </coding>	  	    
      </valueCodeableConcept>	  
    </extension>
  </extension>
  <!-- other data for patient -->
</Patient>

Or in JSON: 

{
  "resourceType" : "Patient",
  "extension" : [{
    "url" : "http://hl7.org/fhir/StructureDefinition/patient-clinicalTrial",
    "extension" : [{
      "url" : "NCT",
      "valueString" : "123456789"
    }, {
      "url" : "period", 
      "valuePeriod" : {
         "start" : "2009-03-14" 
      }   
    },  {
      "url" : "reason",
      "valueCodeableConcept" : {
          "coding" : {
             "system" : "http://acme.org/codes/general",
             "code" : "tt14j",
          }
       }
    }]
  }]
  ... other data for patient ...
}

As the URL suggests, this extension is defined as part of this specification.

This can be extended again, by adding a "registrar" extension:

The registrar is defined as a separate extension (e.g. by an implementing organization), rather than part of the official clinical-trial extension. The URL of the extension is different: 

<Patient>
  <extension url="http://hl7.org/fhir/StructureDefinition/patient-clinicalTrial" >
    <extension url="NCT" >
      <valueString value="123456789" />
    </extension>
    <extension url="period" >	  
      <valuePeriod>
        <start value="2009-03-14" />	  
      </valuePeriod>
    </extension>
    <extension url="reason" >	  
      <valueCodeableConcept>	  
        <coding>	  	    
          <system value="http://acme.org/codes/general" />	  
          <code value="tt14j" />	  
        </coding>	  	    
      </valueCodeableConcept>	  
    </extension>
  </extension>
    <extension url="http://acme.org/fhir/StructureDefinition/registrar" >	  
      <valueReference>
        <reference value="Practitioner/example" />	  
      </valueReference>
    </extension>
  <!-- other data for patient -->
</Patient>

or in JSON: 

{
  "resourceType" : "Patient",
  "extension" : [{
    "url" : "http://hl7.org/fhir/StructureDefinition/patient-clinicalTrial",
    "extension" : [{
      "url" : "NCT",
      "valueString" : "123456789"
    }, {
      "url" : "period", 
      "valuePeriod" : {
         "start" : "2009-03-14" 
      }   
    },  {
      "url" : "reason",
      "valueCodeableConcept" : {
          "coding" : {
             "system" : "http://acme.org/codes/general",
             "code" : "tt14j",
          }
       }
    },{
      "url" : "http://acme.org/fhir/StructureDefinition/registrar", 
      "valueReference" : {
         "reference" : "Practitioner/example" 
      }   
    }]
  }]
  ... other data for patient ...
}

2.20.0.2 Modifier Extensions

There are some cases where the information provided in an extension 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:

  • An anti-prescription: recording an instruction not to take a medication
  • Using the Condition resource to record an assertion that a patient has a family history of the condition rather than the condition itself
  • Asserting that a performer was not actually involved in a Procedure
  • Asserting an additional subsumption relationship on a concept in a value set

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 such 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, nor can extensions have modifier extensions internally.

Note that complex extensions are allowed to have elements in the complex extension that are marked is modifier = true, in that the modify the extension value itself. Such elements are conveyed using "extension", not "modifierExtension" because the impact of the modifier element is expected to be known by applications that understand the containing extension. Any modifierExtension defined outside an extension cannot be placed in another extension.

DSTU Note: Is this a problem? Input from implementers identiying places where modifier extensions might be needed inside other extensions is welcome here .

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 MedicationOrder to write an "anti-prescription" - an instruction not to take a medication for a particular time. Classical clinical recording systems do not record this as a prescription - but one particular system does, and these "anti-prescription" records need to be shared within the institution where this happens, as they are an important part of the workflow. Hence, applications are allowed to extend a resource with data like this: 

<MedicationOrder>
  <modifierExtension url="http://example.org/fhir/StructureDefinition/anti-prescription">
    <valueBoolean value="true"/>
  </modifierExtension>
  <!-- ... other content ... -->
</MedicationOrder>

Or in JSON: 

{
  "resourceType" : "MedicationOrder",
  "modifierExtension" : [{
    "url" : "http://example.org/fhir/StructureDefinition/anti-prescription",
    "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:

  1. understand the impact of the extension when using the data
  2. refuse to process the data
  3. 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 (a server, for instance, could return a HTTP 422 status code with an OperationOutcome if a client PUTs or POSTs a modifier extension it does not know. Applications may also be able to ignore a modifier extension if they 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 prescription example from above with narrative: 

<MedicationOrder xmlns="http://hl7.org/fhir">
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p><b>Note: This prescription is an instruction NOT to take a medication</b></p>
      <!-- snip actual narrative -->
    </div>
  </text>
  <!-- ...data... -->
  <modifierExtension url="http://example.org/fhir/StructureDefinition/anti-prescription">
    <valueBoolean value="true"/>
  </modifierExtension>
  <!-- ...data... -->
</MedicationOrder>

An application only needs to concern itself with modifierExtensions on elements that it processes. Take, for example, the case above where a procedure resource has a modifierExtension on one of the performer elements indicating that they did not participate in the procedure. In this case, if an application is not using the performer details 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 must act in one of the ways outlined above.

2.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

2.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/StructureDefinition/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.

2.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 be made around how the data in extensions contain should be handled, along with the implicit obligations that surround 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.

2.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, read and process the extensions you know and use, and ignore other extensions
  • Retain extensions whenever you can