This page is part of the FHIR Specification (v0.01: Historical Archive 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

Extensibility

This exchange specification is based on generally agreed common requirements across healthcare - many jurisdications, domains, and different functional approaches. As such, it is common for specific implementations to have valid requirements that will not be adopted by this specification. Adopting all of these requirements would make this specification very cumbersome and difficult to implement. Instead, this specification expects that these additional common requirements will be implemented as extensions.

As such, extensibility is a fundamental part of the design of this specifications. Every resource includes an extensions 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, whatever institution or jurisdiction uses or defines them; their use of such extensions is what allows the 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 reqiurements that must be met as part of the definition of the extension.

Extensibility Element

Each resource includes the optional extensions element before the narrative element at the end of the resource.

<x xmlns="http://www.hl7.org/fhir">
  <code> mand id Code that identifies the meaning of the extension</code>
  <definition> mand uri Source of the definition for the code</definition>
  <ref> opt id Internal reference to context of the extension (xml:id)</ref>
  <state> opt code must-understand | superceded</state>
  <value[x]> cond Value of extension</value[x]>
  <extension> cond  <!-- Zero+ Nested Extensions -->
    <!-- Content as for Extension -->
  </extension>
</x>

Terminology Bindings

• Extension.state is bound to the concept domain ExtensionState: "The state of an extension". Possible values:

  must-understand	The extension contains information that qualifies or negates another element, and must be understood by an application processing the resource
  superceded	The extension has been promoted into the main content of the resource, and the content is found at the reference. The extension continues to be defined for backward compatibility

Notes:

• The code identifies the meaning of the extension. The only codes that can be used are those defined using the methodology described below.
• The source of the definition must be declared using the definition element. The definition may point directly to a computable or human readable definition of the extensibility codes, or it may be a logical URI as declared in some other specification. The definition should be version specific.
• If present, the id in the ref element identifies a target element that is extended by the content as if it contained the extension itself. The id must point within the same resource
• The order that extensions appear in is significant - where multiple extensions have the same ref id, they extend the target element in the order in which they appear in the extensions
• When using xml:id attributes, the comments in the aggregation section about the value of the xml:id attribute should be kept in mind
• Any element defined as part of the resource content, or any repeating element inside a data type, may carry an id attribute to serve as the target of an extension
• An extension may have a value, or nested extensions, but not both. The actual name of the value element has the type added to it in place of the [x], such as valueQuantity

As well as providing additional undescribed information, extensions may be used to qualify the meaning of other elements in a way that makes them unsafe to ignore, or even to negate the meanings of other elements. Such extensions must have a state of "must-understand". Over time, an extension may be promoted to become part of the resource itself. In order to properly send the data, the extension should still be present, but should have no value element. Instead, the state of the extension is "superceded", and the ref points to the correct location for the data.

Any application processing the data of a resource must check for extensions with state="must-understand". If the application does not recognise the code on an extension that is labeled "must-understand", and where the extension either has no internal reference, or the reference is data processed by the application, it 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 labelled as must-understand must be represented in the narrative. Applications are encouraged to ignore un-required extensions that they do not recognise. Applications that do not accept unknown extensions should declare this in their conformance statement.

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:

• dateTime
• string
• uri
• humanDate
• Attachment
• CodeableConcept
• Coding
• Identifier
• Quantity
• Choice
• Interval_Quantity
• Interval_humanDate
• Ratio
• HumanId
• HumanName
• Address
• Contact

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.

Defining Extensions

Extensions may be defined by any project or jurisdication, up to and including international standards organisations such as HL7 itself.

Extensions are always defined against some particular context. The following are possible contexts for an extension:

• A particular element in a single resource
• Anywhere a particular data type is used
• A set of elements across one or more resources
• a particular context in one of the mapped reference models
• Another extension

In addition, an element definition might apply additional constraints with regards to particular element values of the target that make it's use appropriate. Extensions SHALL only be used in the contect against which they are defined.

Each extension is defined using the following fields:

todo: metadata, context

Code	Required	The code that is used in a resource to identify this extension
Context	Required	The context of this extension. See below
TargetType	Optional	The type of the path to which this applies, if it matters. This must be a valid FHIR data type as described above
Cardinality	Required	The cardinality of this extension. Specifying a minimum cardinality of 1 means that if the source system declares that it conform to the set of extensions containing this extension, it must be included in the resource
Conformance	Required	Whether the use of the extension is mandatory, conditional, optional, or prohibited. If the extension is conditional, the conditions must be described in the comments field. This field overlaps with the cardinality, and must be consistent with it.
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
Concept Domain	Conditional	For the types CodeableConcept and Coding. see Terminologies
Must Understand	Required	Whether the extension must be understood by any system reading the resource. There is 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
Definition	Required	A formal statement of the meaning of the content of the field
Requirements	Required	Discussion of the reason for the extension / what use cases it was defined to handle
Comments	Optional	Additional other information about the extension, including information concerning it's conditionality if indicated in the conformance field
RIM Mapping	Conditional	The formal mapping from this extension to the RIM. Required for HL7 defined extensions, but may be optional in other contexts
v2 Mapping	Optional	Mapping to a v2 segment/field/etc, if desired and appropriate.

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 must be available to all the parties that share the resources. Each extension contains a URI that references the source of the definitions. The source can be a literal reference, such as an http: url that refers to an end-point that responds with the contents of the definitions, or a logical reference (e.g. using a urn:) - for instance, to a national published standard. Literal references are preferred.

Whether the reference is a literal or logical reference, the extension definitions must be published using the fields defined as above. They may be published in narrative form, possibly as part of a larger specification. This narrative form is for human consumption. In addition, they may be published in a structured form, as either a csv file, or an XML file. The CSV file should have the fields described above as columns in the order described above, with a title row containing the case sensitive field names as above. XML files should use the format described in the XML Definitions schema (note that element and extension definitions from FHIR itself also use the same format).

Todo: extension packs & metadata Control * resources are balloted * implementations (jurisdictions, institutions, projects) must publish their extensions through HL7 extension registry/repository (will be distributed?) * extensions may be submitted to HL7 for endorsement. Committees approve them by in-committee vote, and then HL7 publishes them with endorsement * extensions should never be redefined once in used. (endorsed extensions can't have their RIM mappings changed)

As well as defining the base element structure for resources, HL7 also publishes extensions. When HL7 itself publishes extensions as part of the FHIR specification, these extensions must be used for this data whenever the data is represented in instances. 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 implementors 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 it anyway.

Implementations are encouraged to share their extensions with HL7; the domain committees will work to elevate the extensions into HL7 published extensions or the into the base resource structure itself.

---

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.01 generated on Mon, May 14, 2012 09:48+1000.