2nd DSTU Draft For Comment

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

6.20 Resource ExtensionDefinition - Content

This resource maintained by the FHIR Management Group Work Group

Defines an extension that can be used in resources.

6.20.1 Scope and Usage

The Extension Definition resource provides a formal definition of an extension used in a FHIR resource, that can used as the basis for validation, and code, report and UI generation.

6.20.2 Boundaries and Relationships

  • Every extension in a resource refers directly to it's definition
  • ExtensionDefinitions are used by Profile instances when specifying that extensions are used in a resource

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.

6.20.3 Background and Context

Extensions may be defined by any project or jurisdiction, up to and including international standards organizations such as HL7 itself. 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 typeContext formatExamples
A particular element (including the root) in a single resourceThe element path for that element
Note: If the context is an element that can have multiple types, then use (e.g.) value[x] if the extension works on all choice types, or otherwise an enumeration of explicitly named elements if not		Profile.resource.element; Person
A particular element (including the root) in a particular data typeThe data type name for primitive types or the element path for complex data typesAddress.part.value; string
A particular context in one of the mapped reference modelsThe name of the reference model followed by the mapping pathRIM: Act[moodCode="EVN"]
Another extensionThe profile uri of the extension followed by the extension codehttp://myextensions.org#someExtension
A set of some combination of the aboveAs 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.

6.20.4 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ExtensionDefinition IDomainResourceExtension Definition
All element names must start with the extension name
... url 1..1uriLiteral URL used to reference this extension
... identifier Σ0..*IdentifierOther identifiers for the extension
... version Σ0..1stringLogical id for this version of the extension
... name Σ1..1stringDescriptional name for this profile
... display 0..1stringUse this name when displaying the value
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*ElementContact details of the publisher
.... name Σ0..1stringName of a individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... description Σ0..1stringNatural language description of the extension
... code Σ0..*CodingAssist with indexing and finding
... status M Σ1..1codedraft | active | retired
ResourceProfileStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... date Σ0..1dateTimeDate for this version of the extension
... requirements 0..1stringScope and Usage this extesion is for
... mapping I0..*ElementExternal specification that the content is mapped to
Must have at a name or a uri (or both)
.... identity 1..1idInternal id when this mapping is used
.... uri I0..1uriIdentifies what this mapping refers to
.... name I0..1stringNames what this mapping refers to
.... comments 0..1stringVersions, Issues, Scope limitations etc
... contextType 1..1coderesource | datatype | mapping | extension
ExtensionContext (Required)
... context 1..*stringWhere the extension can be used in instances
... element I1..*ElementDefinitionDefinition of the elements in the extension
Path names cannot contain .value

UML Diagram

ExtensionDefinition (DomainResource)The URL at which this definition is (or will be) published, and which is used to reference this profile in extension urls in operational FHIR systemsurl : uri 1..1Formal identifier that is used to identify this profile when it is represented in other formats (e.g. ISO 11179(, or referenced in a specification, model, design or an instance (should be globally unique OID, UUID, or URI), (if it's not possible to use the literal URI)identifier : Identifier 0..*The identifier that is used to identify this version of the extension definition when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the author manuallyversion : string 0..1A free text natural language name identifying the extensionname : string 1..1Defined so that applications can use this name when displaying the value of the extension to the userdisplay : string 0..1The name of the individual or organization that published the extension definitionpublisher : string 0..1A free text natural language description of the extension and its usedescription : string 0..1A set of terms from external terminologies that may be used to assist with indexing and searching of extension definitionscode : Coding 0..*The status of the extension (this element modifies the meaning of other elements)status : code 1..1 « The lifecycle status of a Resource ProfileResourceProfileStatus »This extension definition was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean 0..1The date that this version of the extension was publisheddate : dateTime 0..1The Scope and Usage that this extension was created to meetrequirements : string 0..1Identifies the type of context to which the extension appliescontextType : code 1..1 « How an extension context is interpretedExtensionContext »Identifies the types of resource or data type elements to which the extension can be appliedcontext : string 1..*Definition of the elements that are defined to be in the extensionelement : ElementDefinition 1..*ContactThe name of an individual to contact regarding the extension definitionname : string 0..1Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint 0..*MappingAn Internal id that is used to identify this mapping set when specific mappings are madeidentity : id 1..1A URI that identifies the specification that this mapping is expressed touri : uri 0..1A name for the specification that is being mapped toname : string 0..1Comments about this mapping, including version notes, issues, scope limitations, and other important notes for usagecomments : string 0..1Contacts to assist a user in finding and communicating with the publishercontact0..*An external specification that the content is mapped tomapping0..*

XML Template

<ExtensionDefinition xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 1..1 Literal URL used to reference this extension -->
 <identifier><!-- 0..* Identifier Other identifiers for the extension --></identifier>
 <version value="[string]"/><!-- 0..1 Logical id for this version of the extension -->
 <name value="[string]"/><!-- 1..1 Descriptional name for this profile -->
 <display value="[string]"/><!-- 0..1 Use this name when displaying the value -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) -->
 <contact>  <!-- 0..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of a individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <description value="[string]"/><!-- 0..1 Natural language description of the extension -->
 <code><!-- 0..* Coding Assist with indexing and finding --></code>
 <status value="[code]"/><!-- 1..1 draft | active | retired -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date for this version of the extension -->
 <requirements value="[string]"/><!-- 0..1 Scope and Usage this extesion is for -->
 <mapping>  <!-- 0..* External specification that the content is mapped to -->
  <identity value="[id]"/><!-- 1..1 Internal id when this mapping is used -->
  <uri value="[uri]"/><!-- ?? 0..1 Identifies what this mapping refers to -->
  <name value="[string]"/><!-- ?? 0..1 Names what this mapping refers to -->
  <comments value="[string]"/><!-- 0..1 Versions, Issues, Scope limitations etc -->
 </mapping>
 <contextType value="[code]"/><!-- 1..1 resource | datatype | mapping | extension -->
 <context value="[string]"/><!-- 1..* Where the extension can be used in instances -->
 <element><!-- ?? 1..* ElementDefinition Definition of the elements in the extension --></element>
</ExtensionDefinition>

JSON Template

{doco
  "resourceType" : "ExtensionDefinition",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // R! Literal URL used to reference this extension
  "identifier" : [{ Identifier }], // Other identifiers for the extension
  "version" : "<string>", // Logical id for this version of the extension
  "name" : "<string>", // R! Descriptional name for this profile
  "display" : "<string>", // Use this name when displaying the value
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of a individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "description" : "<string>", // Natural language description of the extension
  "code" : [{ Coding }], // Assist with indexing and finding
  "status" : "<code>", // R! draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Date for this version of the extension
  "requirements" : "<string>", // Scope and Usage this extesion is for
  "mapping" : [{ // External specification that the content is mapped to
    "identity" : "<id>", // R! Internal id when this mapping is used
    "uri" : "<uri>", // C? Identifies what this mapping refers to
    "name" : "<string>", // C? Names what this mapping refers to
    "comments" : "<string>" // Versions, Issues, Scope limitations etc
  }],
  "contextType" : "<code>", // R! resource | datatype | mapping | extension
  "context" : ["<string>"], // R! Where the extension can be used in instances
  "element" : [{ ElementDefinition }] // C? R! Definition of the elements in the extension
}

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. ExtensionDefinition IDomainResourceExtension Definition
All element names must start with the extension name
... url 1..1uriLiteral URL used to reference this extension
... identifier Σ0..*IdentifierOther identifiers for the extension
... version Σ0..1stringLogical id for this version of the extension
... name Σ1..1stringDescriptional name for this profile
... display 0..1stringUse this name when displaying the value
... publisher Σ0..1stringName of the publisher (Organization or individual)
... contact Σ0..*ElementContact details of the publisher
.... name Σ0..1stringName of a individual to contact
.... telecom Σ0..*ContactPointContact details for individual or publisher
... description Σ0..1stringNatural language description of the extension
... code Σ0..*CodingAssist with indexing and finding
... status M Σ1..1codedraft | active | retired
ResourceProfileStatus (Required)
... experimental Σ0..1booleanIf for testing purposes, not real usage
... date Σ0..1dateTimeDate for this version of the extension
... requirements 0..1stringScope and Usage this extesion is for
... mapping I0..*ElementExternal specification that the content is mapped to
Must have at a name or a uri (or both)
.... identity 1..1idInternal id when this mapping is used
.... uri I0..1uriIdentifies what this mapping refers to
.... name I0..1stringNames what this mapping refers to
.... comments 0..1stringVersions, Issues, Scope limitations etc
... contextType 1..1coderesource | datatype | mapping | extension
ExtensionContext (Required)
... context 1..*stringWhere the extension can be used in instances
... element I1..*ElementDefinitionDefinition of the elements in the extension
Path names cannot contain .value

UML Diagram

ExtensionDefinition (DomainResource)The URL at which this definition is (or will be) published, and which is used to reference this profile in extension urls in operational FHIR systemsurl : uri 1..1Formal identifier that is used to identify this profile when it is represented in other formats (e.g. ISO 11179(, or referenced in a specification, model, design or an instance (should be globally unique OID, UUID, or URI), (if it's not possible to use the literal URI)identifier : Identifier 0..*The identifier that is used to identify this version of the extension definition when it is referenced in a specification, model, design or instance. This is an arbitrary value managed by the author manuallyversion : string 0..1A free text natural language name identifying the extensionname : string 1..1Defined so that applications can use this name when displaying the value of the extension to the userdisplay : string 0..1The name of the individual or organization that published the extension definitionpublisher : string 0..1A free text natural language description of the extension and its usedescription : string 0..1A set of terms from external terminologies that may be used to assist with indexing and searching of extension definitionscode : Coding 0..*The status of the extension (this element modifies the meaning of other elements)status : code 1..1 « The lifecycle status of a Resource ProfileResourceProfileStatus »This extension definition was authored for testing purposes (or education/evaluation/marketing), and is not intended to be used for genuine usageexperimental : boolean 0..1The date that this version of the extension was publisheddate : dateTime 0..1The Scope and Usage that this extension was created to meetrequirements : string 0..1Identifies the type of context to which the extension appliescontextType : code 1..1 « How an extension context is interpretedExtensionContext »Identifies the types of resource or data type elements to which the extension can be appliedcontext : string 1..*Definition of the elements that are defined to be in the extensionelement : ElementDefinition 1..*ContactThe name of an individual to contact regarding the extension definitionname : string 0..1Contact details for individual (if a name was provided) or the publishertelecom : ContactPoint 0..*MappingAn Internal id that is used to identify this mapping set when specific mappings are madeidentity : id 1..1A URI that identifies the specification that this mapping is expressed touri : uri 0..1A name for the specification that is being mapped toname : string 0..1Comments about this mapping, including version notes, issues, scope limitations, and other important notes for usagecomments : string 0..1Contacts to assist a user in finding and communicating with the publishercontact0..*An external specification that the content is mapped tomapping0..*

XML Template

<ExtensionDefinition xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <url value="[uri]"/><!-- 1..1 Literal URL used to reference this extension -->
 <identifier><!-- 0..* Identifier Other identifiers for the extension --></identifier>
 <version value="[string]"/><!-- 0..1 Logical id for this version of the extension -->
 <name value="[string]"/><!-- 1..1 Descriptional name for this profile -->
 <display value="[string]"/><!-- 0..1 Use this name when displaying the value -->
 <publisher value="[string]"/><!-- 0..1 Name of the publisher (Organization or individual) -->
 <contact>  <!-- 0..* Contact details of the publisher -->
  <name value="[string]"/><!-- 0..1 Name of a individual to contact -->
  <telecom><!-- 0..* ContactPoint Contact details for individual or publisher --></telecom>
 </contact>
 <description value="[string]"/><!-- 0..1 Natural language description of the extension -->
 <code><!-- 0..* Coding Assist with indexing and finding --></code>
 <status value="[code]"/><!-- 1..1 draft | active | retired -->
 <experimental value="[boolean]"/><!-- 0..1 If for testing purposes, not real usage -->
 <date value="[dateTime]"/><!-- 0..1 Date for this version of the extension -->
 <requirements value="[string]"/><!-- 0..1 Scope and Usage this extesion is for -->
 <mapping>  <!-- 0..* External specification that the content is mapped to -->
  <identity value="[id]"/><!-- 1..1 Internal id when this mapping is used -->
  <uri value="[uri]"/><!-- ?? 0..1 Identifies what this mapping refers to -->
  <name value="[string]"/><!-- ?? 0..1 Names what this mapping refers to -->
  <comments value="[string]"/><!-- 0..1 Versions, Issues, Scope limitations etc -->
 </mapping>
 <contextType value="[code]"/><!-- 1..1 resource | datatype | mapping | extension -->
 <context value="[string]"/><!-- 1..* Where the extension can be used in instances -->
 <element><!-- ?? 1..* ElementDefinition Definition of the elements in the extension --></element>
</ExtensionDefinition>

JSON Template

{doco
  "resourceType" : "ExtensionDefinition",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "url" : "<uri>", // R! Literal URL used to reference this extension
  "identifier" : [{ Identifier }], // Other identifiers for the extension
  "version" : "<string>", // Logical id for this version of the extension
  "name" : "<string>", // R! Descriptional name for this profile
  "display" : "<string>", // Use this name when displaying the value
  "publisher" : "<string>", // Name of the publisher (Organization or individual)
  "contact" : [{ // Contact details of the publisher
    "name" : "<string>", // Name of a individual to contact
    "telecom" : [{ ContactPoint }] // Contact details for individual or publisher
  }],
  "description" : "<string>", // Natural language description of the extension
  "code" : [{ Coding }], // Assist with indexing and finding
  "status" : "<code>", // R! draft | active | retired
  "experimental" : <boolean>, // If for testing purposes, not real usage
  "date" : "<dateTime>", // Date for this version of the extension
  "requirements" : "<string>", // Scope and Usage this extesion is for
  "mapping" : [{ // External specification that the content is mapped to
    "identity" : "<id>", // R! Internal id when this mapping is used
    "uri" : "<uri>", // C? Identifies what this mapping refers to
    "name" : "<string>", // C? Names what this mapping refers to
    "comments" : "<string>" // Versions, Issues, Scope limitations etc
  }],
  "contextType" : "<code>", // R! resource | datatype | mapping | extension
  "context" : ["<string>"], // R! Where the extension can be used in instances
  "element" : [{ ElementDefinition }] // C? R! Definition of the elements in the extension
}

 

Alternate definitions: Schema/Schematron, Resource Profile (XML, JSON), Questionnaire

6.20.4.1 Terminology Bindings

PathDefinitionTypeReference
ExtensionDefinition.status The lifecycle status of a Resource ProfileFixedhttp://hl7.org/fhir/resource-profile-status
ExtensionDefinition.contextType How an extension context is interpretedFixedhttp://hl7.org/fhir/extension-context

6.20.4.2 Constraints

  • exd-1: On ExtensionDefinition.mapping: Must have at a name or a uri (or both) (xpath on f:ExtensionDefinition/f:mapping: exists(f:uri) or exists(f:name))
  • exd-2: All element names must start with the extension name (xpath: count(f:element)=count(f:element[(not(preceding-sibling::f:element) and f:path/@value='Extension') or (preceding-sibling::f:element and starts-with(f:path/@value, concat('Extension', '.')))]))
  • exd-3: On ExtensionDefinition.element: Path names cannot contain .value (xpath on f:ExtensionDefinition/f:element: not(contains(f:path/@value, '.value')))

6.20.4.3 Publishing Extension Definitions

As well as defining the base element structure for resources, HL7 also publishes extensions. HL7 publishes such 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, 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 with 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 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 extension definition registries.

RegistrySearchSubmit
HL7 Approved[TBD][TBD]
Community[TBD][TBD]
Interimhttp://fhir-dev.healthintersections.com.au/open/ExtensionDefinition/_search http://fhir.healthintersections.com.au/open/ExtensionDefinition/upload

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

6.20.5 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

NameTypeDescriptionPaths
codetokenAssist with indexing and findingExtensionDefinition.code
datedateDate for this version of the extensionExtensionDefinition.date
descriptionstringNatural language description of the extensionExtensionDefinition.description
identifiertokenOther identifiers for the extensionExtensionDefinition.identifier
namestringDescriptional name for this profileExtensionDefinition.name
publisherstringName of the publisher (Organization or individual)ExtensionDefinition.publisher
statustokendraft | active | retiredExtensionDefinition.status
urltokenLiteral URL used to reference this extensionExtensionDefinition.url
valuesetreferenceSource of value setExtensionDefinition.element.binding.reference[x]
(ValueSet)