This page explains how the Cloud Healthcare API supports FHIR extensions.
Overview
FHIR allows user-defined extensions on resources and data types. The Cloud Healthcare API supports storing and retrieving these extensions.
Extension values
An extension element is a key-value pair. The key, stored in the url
field, indicates the canonical URL of an extension definition that defines
the content and meaning of the extension. The value
field is a choice element
that can contain many different FHIR data types.
This mechanism is the same across all FHIR versions, except that earlier versions have fewer available data types. The available data types for extensions can be found in the FHIR standard (DSTU2, STU3, R4).
The following example shows a Patient
resource with two extensions, hair color
and citizenship, on the root element:
{
"resourceType": "Patient",
"active": true,
"gender": "male",
"extension": [
{
"url": "http://example.com/fhir/StructureDefinition/hair-color",
"valueString": "brown"
},
{
"url": "http://example.com/fhir/StructureDefinition/patient-citizenship",
"valueCodeableConcept": {
"coding" : [{
"system" : "urn:iso:std:iso:3166",
"code" : "US"
}]
}
}
]
}
Complex data types and elements with child fields can also have extensions; for
example, this Patient
contains an extension on the identifier
field which is
a complex data type and an extension on the communication
field which has
other child fields:
{
"resourceType": "Patient",
"active": true,
"gender": "male",
"identifier": [
"system": "MRN",
"value": "AB1234",
"extension": [
{
"url": "http://example.com/fhir/StructureDefinition/last-verified",
"valueDateTime": "2021-01-01T00:00:00Z"
}
]
],
"communication": [
{
"language": {
"coding": [{
"system": "urn:iso:std:iso:639",
"code": "EN"
}]
},
"extension": [
{
"url": "http://example.com/fhir/StructureDefinition/fluency-level",
"valueInteger": 7
}
]
}
]
}
Each extension element can only have a single value field. To define an
extension that contains an array of values, you must define multiple extension
elements with the same url
.
You can't define extensions on the root element for the following resource types:
Binary
Bundle
Parameters
Complex extensions
Extensions can contain extensions to define a nested structure. The url
name
of the child extension is relative to the outer extension. Each extension
element must have either a value element or a nested child extension, but not
both.
The following example shows a Patient
resource that contains a complex
patient-citizenship
extension with child extensions code
and period
:
{
"resourceType": "Patient",
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/patient-citizenship",
"extension": [
{
"url": "code",
"valueCodeableConcept": {
"coding": [{
"system": "urn:iso:std:iso:3166",
"code": "CA"
}]
}
},
{
"url": "period",
"valuePeriod": {
"start": "2010-01-01"
}
}
]
}
]
}
Extensions on primitive types
Primitive data types in FHIR can also have extensions. When represented in
JSON format the extensions are represented in an additional JSON property with
_
prepended to the name of the primitive element, as defined in the
FHIR JSON representation.
The following example, in JSON format, shows a Patient
resource with an
extension on the birthDate
field:
{
"resourceType": "Patient",
"active": true,
"gender": "male",
"birthDate": "1970-01-01",
"_birthDate": {
"extension": [
{
"url": "http://example.com/fhir/StructureDefinition/date-type",
"valueString": "A"
}
]
}
}
If the primitive element is repeated, the property with _
is also handled as
an array, with null values used to align extension values with their
corresponding primitives.
The following example shows a Patient
resource with an extension on
the second value of name.given
but no extension on the first value:
{
"resourceType": "Patient",
"name": {
"given": [
"ABC",
"DEF"
],
"_given": [
null,
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/display",
"valueString": "XYZ"
}
]
}
]
}
}
Defining an extension with a StructureDefinition
For the purposes of interoperability, the name and meaning of an extension can
be defined with a StructureDefinition
resource that can be published or
distributed to enable consumers of the data to interpret it. This is optional
when using extensions in the Cloud Healthcare API.
The identity of this definition is indicated by the canonical url
in the 'url' field. For any data that is exchanged between organizations,
it is recommended to use a URL that data consumers can follow
to obtain the StructureDefinition
. The Cloud Healthcare API does not
validate this URL or attempt to resolve it.
The contents of a StructureDefinition
resource can be complex and are often
defined using tools for authoring FHIR profiles.
Modifier extensions
Modifier extensions
are similar to extensions, but are stored in the modifierExtension
field. A
modifier extension is additional data that can't be ignored because it could
invalidate the interpretation of the element that contains it.
For example, a modifier extension could indicate that the patient does not have the specified condition or that a drug must not be prescribed.
The Cloud Healthcare API stores and retrieves modifier extensions but does not attempt to interpret their meaning. Applications are advised to take appropriate action when encountering a modifier extension that they do not understand, possibly by displaying a warning or rejecting the resource entirely. Implementers should avoid the use of modifier extensions where possible.