FHIR extensions

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.