FHIR Release 3 (STU) 4

This page is part of the FHIR Specification (v3.0.2: (v4.0.1: R4 - Mixed Normative and STU 3). ) in it's permanent home (it will always be available at this URL). 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 R4 R3 R2

2.5.1 Defining Extensions

FHIR Infrastructure Work Group Maturity Level : 3 Ballot Standards Status : Trial Use Normative
This page has been approved as part of an ANSI standard. See the Infrastructure Package for further details.

All extensions used in resources require a formal published definition which that can be used by application developers, developers or the applications themselves, to help integrate extensions into the healthcare process they support.

Every extension in a resource refers directly to its definition, which is made available as a StructureDefinition . A resource can be profiled to specify where particular extensions are used. required or expected.

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 StructureDefinition . 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, StructureDefinition , or a logical reference (e.g. using a urn:) - for instance, to a national published standard. Extensions may be defined by any project or jurisdiction, up to and including international standards organizations such as HL7 itself.

Before defining a new extension, attempt to reuse existing extensions defined in one of the shared registries described below . Also consider that some concepts may be appropriate to add as part of the core specification.

See also Best Practice Guidance for defining extensions .

2.5.1.1 Core Elements

Elements are included as part of FHIR resources and data types principally on the basis of current world-wide usage patterns. Policy is that if a significant majority of systems throughout the world that would use a resource or data type would use an element, then that element will be included as part of the resource/data type. If not, it will be left to an extension. This holds even if the element is very common or even mandatory in one or two specific jurisdictions.

Proposals suggesting a new core element can be raised by anyone. (Free registration is required.) However, given the timelines for new FHIR releases as well as the uncertainties associated with vetting the specification through a ballot process, it may still be necessary to define extensions even for elements that are likely to be supported as part of the core specification in a future release.

2.5.1.2 Context

Extensions are always defined against some particular context - the type of element that which elements they may be used to can extend. The following There are possible contexts for three different ways to specify which elements an extension: extension can be found on:

Code Context type Context format Examples
resource fhirpath A particular element (including FHIRPath expression that selects the root) in a single resource set of elements on which the extension can appear The element path for FHIRPath statement always starts from the root of the resource that element, using might contain the standard dotted notation element Condition
Condition.code (Condition | Observation).code
datatype A particular element (including the root) in a particular data type The data type name Formal Element Id for primitive types or the element path for complex data types. These extensions can be used anywhere the data type is used Address.part.value string mapping A particular context in one of Element Ids are unique within the mapped reference models base specification, and within a structure definition. The name of the reference model followed by full path for the mapping path. The details of element is [url]#[elementid]. If there is no #, the path depend on Element id is one defined in the named mapping base specification RIM: Act[moodCode="EVN"] Address.part.value
http://hl7.org/fhir/StructureDefinition/resprate#Observation.category:vscat.coding
extension Another extension The profile URI canonical URL of the extension extension, optionally followed by the #code for extension that appear within a complex extension code http://myextensions.org/someExtension http://hl7.org/fhir/StructureDefinition/device-din

Note: For type 'resource' and 'datatype', if the context is an element that can have multiple types, then use either the [x] qualified name (e.g. Observation.value[x]) if the extension works on all choice types, or an enumeration of explicitly named elements if not (e.g. Observation.valueQuantity) In addition, the 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. that appears in their context list.

2.5.1.3 Cardinality

The cardinality constraints asserted by the extension definition itself apply to any contexts where the extension is used.

Minimum Cardinality

If the Extension minimum cardinality is 0, then the extension is is, by default, optional anywhere it appears. A profile that defines the use of an extension may make the minimum cardinality any number up to the maximum cardinality of the extension itself. Example: Example: Patient birthplace .

If the Extension minimum cardinality is > 1, then the extension must have a minimum cardinality of at least the minimum cardinality in any profile that defines the use of the extension. The minimum cardinality may be any number up to the maximum cardinality of the extension. Even with a minimum cardinality > 0, the extension is only required to be present in instances if the instances explicitly or implicitly conform to a profile that defines the use of the extension. Example: CapabilityStatement Expectation .

Maximum Cardinality

If the Extension maximum cardinality is 1, then the extension is only allowed once on any element on which it appears. A profile that defines the use of an extension can only make the maximum cardinality 1 (or zero if the minimum cardinality is 0, and the profile constrains another profile that allows the extension). Example: Mother's Maiden Name .

If the Extension maximum cardinality is >1, then the extension is allowed up to the specified number of times on any element on which it appears. A profile that defines the use of an extension may make the maximum cardinality any value up to the specified maximum. Example: Patient Disability .

Context Invariants

Extensions are also able to define context invariants, which is a rule that is executed on the element that contains the extension when it is present to check that local requirements around cardinality and other business rules are met.

For example, if you use the extension for house number , the Address.line needs to be filled as well: 


  <contextInvariant value="line.exists()"/>

Note that since the context invariant is only evaluated when the extension is present, there is an implicit "line.extension('http://hl7.org/fhir/StructureDefinition/iso21090-ADXP-streetName').exists() implies" at the start of the expression. A context invariant that enforces that the extension is present under certain circumstances cannot be defined in the extension itself - it must be defined in a profile that makes use of the extension.

2.5.1.4 Use of ElementDefinition in Extension Definitions

An extension is a wrapper for an identifying url and either a value or other extensions. As such, some of the properties of the extension are defined on the extension itself, while others are defined on the Extension.value . This list provides guidance for the correct usage:

  • Extension root element:
    • Cardinality
    • Short, Definition, Comments
    • IsModifier
    • MustSupport (is used on invocation of the extension)
    • Conditions & Constraints. These SHOULD never be on url/value[x]
    • Mappings. these SHALL never be on url/value[x]
  • Extension.url Extension.url:
    • Cardinality = 1...1 (fixed)
    • value = canonical url URL (fixed)
  • Extension.value[x]:
      Extension.value[x]
    • Type
    • Cardinality for Simple extensions (not nested): 1...1. 1..1. Use 0..0 if nested. Note that the actual ED extension cardinality is defined by the root element
    • Binding
    • MaxLength, DefaultValue, Pattern, Example, MinValue, MaxValue
  • Extension.extension:
    • Cardinality for Complex extensions (nested): 0..*, though at least one nested extension must be present. Use 0..0 if a simple (non-nested extension)
    • .extension is automatically sliced by url
    • nested extensions can be defined in-line (as children elements of Extension.extension), or by reference (using .type.profile)

Note: Extensions are always sliced by their url property. Re-slicing extensions by additional properties is allowed (see Profiling/Slicing ).

2.5.1.5 Publishing Extension Definitions

As well as defining the base element structure for resources, HL7 also publishes extensions, including as part of this specification . HL7 publishes such data definitions as extensions rather than as part of the base resource structure to keep the base resource structure simple and concise, and to allow implementers freedom from needing to engage with an entire world's worth of functionality up front. Note that HL7 does not generally define "modifier" extensions - if HL7 publishes an element that modifies the meaning of other elements, it will generally be part of the resource content itself, since everyone has to understand the extension anyway.

Before extensions can be used in instances, their definition SHALL be published. HL7 maintains two extension registries:

  1. HL7 approved extensions, approved by an appropriate part of the HL7 community following a review process, and which that have formal standing
  2. Provided as a service to the community, where anyone can register an extension

Users are encouraged to register their extensions in the second registry, though 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 only 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 publish it on a public facing web site. Using the HL7 FHIR registry or other publicly accessible extension registries. registries not only publishes the extension, but also makes it easy to find and encourages reuse and therefore consistency across implementations.

The HL7 FHIR registry can be found at http://hl7.org/fhir/registry .

HL7 extension definitions may be balloted alongside resource content as part of the FHIR specification or may be published as part of separate specifications. When HL7 publishes extension definitions 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.

To minimize complexity for implementers, HL7 will not elevate widely adopted extensions (defined by HL7 or other organizations) to be content defined in a core resource in future versions of the resource unless there is widespread endorsement of such a migration from the implementer community. This policy ensures that widespread adoption of an extension does not result in a forced migration to a core element. Extensions labelled labeled as draft may be moved in either direction, but after extensions are finalised finalized as normative they won't be moved.

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 HL7 v2 segments or a HL7 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, 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 SHALL NOT remove or constrain any context previously listed