Creating a primitive extension in a FHIR resource

An extension “extends” or enhances a FHIR resource or a data element in a custom way. The extension can be added to the root of a resource, such as “Patient.ethnicity” in US Core profile, and they can be added to individual elements such as HumanName, Address or Identifier.

Did you know that you can also add an extension to a primitive data type?

Primitives usually store a single item and are the most basic element in FHIR. For example: "Keren", false, 1234, 12/08/2024 etc.

For example, the patient resources might look like this:

The gender, birthDate or family elements are primitive elements, based on primitive datatypes.

How would you add an extension to the birthDate property or to the deceased property?

You will need to create a second attribute of the same name prefixed with an underscore, so the primitive extension for the birthDate property will be _birthdate.

The underscore tells FHIR that you’re accessing the underlying base Element for the primitive data type.

All the elements in FHIR inherit or descend from the base element. It contains two attributes: extension and id.

In the example below I added a “Time of year” extension to birthDate property and an “Is Alive” extension to the deceasedBoolean property.

There are several ways to create a FHIR resource, here is an example on how to add a primitive extension in each of the ways.

1. Using a Dynamic Object to build the FHIR resource

If you create the FHIR resource by using a dynamic object, you can just access the new primitive extension directly:

    set resource = {}

    set resource.resourceType     = "Patient"
    do resource.%Set("active",1,"boolean")
    set resource.gender           = "female"
    set resource.birthDate        = "1984-12-24"
    set resource."_birthDate"     = {}
    set resource."_birthDate".id  = "123456"
    set resource."_birthDate".extension = []

    set extension               = {}
    set extension.url            = "http://example.org/fhir/StructureDefinition/Holiday"
    set extension.valueString   = "Christmas"
    do resource."_birthDate".extension.%Push(extension)
    write resource.toJson()

and this will be the result:

2. Using the HS.FHIR.DTL.VR4.Model.* classes

Also using the HS.FHIR.DTL.VR4.Model.* classes is not recommended, you'll have a primitiveExtension list in each level. You'll add your primitive extensions there, and than just reference your property to that extension index.

Here is a sample using the Data Transformation Builder:

and this is how you would do the same in code:

 // Create a new patient resource
 set resource=##class(HS.FHIR.DTL.vR4.Model.Resource.Patient).%New()

 set resource.active=1
 set resource.gender="female"
 // cretate a new extension
 set extension=##class(HS.FHIR.DTL.vR4.Model.Base.Extension).%New()
 set extension.url="http://example.org/fhir/StructureDefinition/Holiday"
 set extension.valueString="Christmas"
 // Add the extension to the primitive extension list
 do resource.primitiveExtension.Insert(extension)

 // point the property to the extention index (#1 in this example)
 set resource.birthDate=$listbuild("1984-12-24",1)
 write resource.ToJSON().Read()

Basically the property value is a $listbuild function that receives several parameters:

set resource.property = $listbuild(""original property value",<primitive extension index>,...)
 

• The first parameter is the value for the original property - if you wish to omit the original property altogether, just send an empty string instead of a value.
• The second parameter is the index number of the required primitive extension from the primitive extension list
• if you wish to add several primitive extensions to the same property, just add them as well (after adding them first to the primitive extension list of course):

set resource.birthDate=$listbuild("1984-12-24",1,3,4,7)

3. Using the FHIR Object Model classes (from 2024.2)

If you are working in Iris for Health version 2024.2 and up, you might want to do the same using the new FHIR Object Model classes. in those classes the primitive extensions are already defined per each property that has it. So in our case, there is a birthDate property and a _birthDate property as well.

You can use the predefined structures to add a primitive extension:

    #dim patient as HS.FHIRModel.R4.Patient
    #dim extension as HS.FHIRModel.R4.Extension

    set patient=##class(HS.FHIRModel.R4.Patient).%New()
    set patient.gender="female"
    set patient.active=1
    set patient.birthDate="1984-12-24"
    // create a new element
    set element=##class(HS.FHIRModel.R4.Element).%New()
    do element.IncludeExtension()

    // create a new extension
    set extension=element.extension.MakeEntry()
    set extension.url="http://example.org/fhir/StructureDefinition/Holiday"
    set extension.valueString="Christmas"
    // add the extension to the element
    do element.extension.add(extension)
    
    // add the element to the resource
    set patient."_birthDate"=element
    
    write patient.toString()

In any way you wish to work, you can now create a primitive extension like a pro!

Look at the samples in the Open Exchange for all 3 ways:

https://openexchange.intersystems.com/package/FHIR-Primitive-Extension

Keren.