FHIR primitive extensions in JSON

Overview

A FHIR primitive element can have a value and additional Element metadata. In JSON, these two parts use separate sibling properties:

• element contains the primitive value, such as a string, boolean, number, date, or code.
• _element contains the primitive element's optional id and extensions.

For example, status contains the primitive value and _status contains metadata that applies to that same logical element. Include the underscore companion only when the primitive has an id or extension metadata.

Primitive companion rules

• If a primitive has both a value and metadata, include both the value property and its underscore companion.
• An underscore companion object cannot be empty.
• If a primitive has extension metadata but no primitive value, omit the value property and include the underscore companion. The companion must contain an extension; an id alone is not sufficient when the value is absent.
• Each extension object requires a url.
• Each extension object contains either a nested extension array or exactly one concrete value[x] property, such as valueString or valueCode. It cannot contain both.
• Use an extension only when the information cannot be represented by an appropriate core FHIR element.

Primitive value with extension metadata

This Patient includes a birthDate value and a _birthDate companion with the standard HL7 rendered-value extension:

{
  "resourceType": "Patient",
  "identifier": [
    {
      "system": "urn:ddfs:documentation-sample",
      "value": "primitive-value-metadata-example"
    }
  ],
  "birthDate": "1990-03-09",
  "_birthDate": {
    "extension": [
      {
        "url": "http://hl7.org/fhir/StructureDefinition/rendered-value",
        "valueString": "March 9, 1990"
      }
    ]
  }
}

• identifier.system identifies the namespace governing a Patient identifier.
• extension.url identifies the extension definition.

The identifier system and value in this example are not DDFS-defined values. Replace these with an identifier namespace and value for your organization.

Use extension URLs and values defined by the applicable FHIR version or an implementation guide that your integration supports.

Extension metadata without a primitive value

A primitive can have extension metadata even when its value is unavailable. In this example, birthDate is omitted and _birthDate carries the extension:

{
  "resourceType": "Patient",
  "identifier": [
    {
      "system": "urn:ddfs:documentation-sample",
      "value": "extension-only-example"
    }
  ],
  "_birthDate": {
    "extension": [
      {
        "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
        "valueCode": "unknown"
      }
    ]
  }
}

Repeating primitive elements

For a repeating primitive, the values and their metadata use two positionally aligned arrays. Use a JSON null placeholder in the value array when an item has extension metadata but no primitive value. Use null in the underscore array when the corresponding value has no id or extension.

The second given item in this HumanName example has both the value J. and extension metadata. The first entry in _given is null because Avery has no primitive metadata:

{
  "resourceType": "Patient",
  "identifier": [
    {
      "system": "urn:ddfs:documentation-sample",
      "value": "repeating-primitives-example"
    }
  ],
  "name": [
    {
      "family": "Chen",
      "given": [
        "Avery",
        "J."
      ],
      "_given": [
        null,
        {
          "extension": [
            {
              "url": "http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier",
              "valueCode": "IN"
            }
          ]
        }
      ]
    }
  ]
}

Do not omit a placeholder from the middle of either array. Changing its position associates the metadata with a different primitive value.

Validation errors

DDFS rejected a Patient create request that represented _birthDate as a string instead of an object. Both the R4 and R6 ballot 4 endpoints returned HTTP status 400 with a FHIR OperationOutcome. Correct the primitive companion representation and use the issues in the returned OperationOutcome to identify the affected element before retrying.

Top-level primitive companions by resource

The following matrices list the underscore companions for top-level primitive properties in each supported DDFS resource model. A listed companion is optional and is included only when its corresponding primitive element has an id or extension metadata.

Primitive properties inside nested datatypes and backbone elements can also have underscore companions. Those nested properties follow the same FHIR JSON rules but are outside the scope of these matrices.

R4 top-level primitive companions

R6 ballot 4 top-level primitive companions

Subscription OCI Vault extension

The DDFS Subscription OCI Vault secret extension is a regular extension on the root Subscription.extension array. It is not primitive metadata and does not use an underscore companion. See FHIR R6 Subscription OCI Vault Secret Extension.

FHIR JSON specifications

For the complete version-specific JSON representation rules, see:

• FHIR R4 (4.0.1) JSON representation
• FHIR R6 (6.0.0-ballot4) JSON representation
• FHIR R4 general extensions, including data-absent-reason and rendered-value
• FHIR R4 extensibility examples, including the HumanName qualifier extension