Store profiles in Azure API for FHIR

HL7 Fast Healthcare Interoperability Resources (FHIR®) defines a standard and interoperable way to store and exchange healthcare data. Even within the base FHIR specification, it can be helpful to define other rules or extensions based on the context that FHIR is being used. For such context-specific uses of FHIR, FHIR profiles are used for the extra layer of specifications. FHIR profile allows you to narrow down and customize resource definitions using constraints and extensions.

Azure API for FHIR allows validating resources against profiles to see if the resources conform to the profiles. This article guides you through the basics of FHIR profiles and how to store them. For more information about FHIR profiles outside of this article, visit HL7.org.

FHIR profile: the basics

A profile sets additional context on the resource that's represented as a StructureDefinition resource. A StructureDefinition defines a set of rules on the content of a resource or data type, such as what elements a resource has and what values these elements can take.

Some examples of how profiles can modify the base resource are:

• Restrict cardinality: For example, you can set the maximum cardinality on an element to 0, which means that the element is ruled out in the specific context.
• Restrict the contents of an element to a single fixed value.
• Define required extensions for the resource.

A StructureDefinition is identified by its canonical URL: http://hl7.org/fhir/StructureDefinition/{profile}.

Here are some examples.

• http://hl7.org/fhir/StructureDefinition/patient-birthPlace is a base profile that requires information on the registered address of birth of the patient.
• http://hl7.org/fhir/StructureDefinition/bmi is another base profile that defines how to represent Body Mass Index (BMI) observations.
• http://hl7.org/fhir/us/core/StructureDefinition/us-core-allergyintolerance is a US Core profile that sets minimum expectations for AllergyIntolerance resource associated with a patient, and it identifies mandatory fields such as extensions and value sets.

When a resource conforms to a profile, the profile is specified inside the profile element of the resource. Following is an example of the beginning of a Patient resource, which has the profile http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient.

{
  "resourceType" : "Patient",
  "id" : "ExamplePatient1",
  "meta" : {
    "lastUpdated" : "2020-10-30T09:48:01.8512764-04:00",
    "source" : "Organization/PayerOrganizationExample1",
    "profile" : [
      "http://hl7.org/fhir/us/carin-bb/StructureDefinition/C4BB-Patient"
    ]
  },

Profiles are specified by various Implementation Guides (IGs). The following is a list of common IGs. For more information, visit the specific IG site to learn more about the IG and the profiles defined within it.

• US Core
• CARIN Blue Button
• Da Vinci Payer Data Exchange
• Argonaut

Accessing profiles and storing profiles

Storing profiles

To store profiles in Azure API for FHIR, you can PUT the StructureDefinition with the profile content in the body of the request. An update or a conditional update are both good methods to store profiles on the FHIR service. Use the conditional update if you're unsure which to use.

Standard PUT: PUT http://<your Azure API for FHIR base URL>/StructureDefinition/profile-id

or

Conditional update: PUT http://<your Azure API for FHIR base URL>/StructureDefinition?url=http://sample-profile-url

{ 
"resourceType" : "StructureDefinition",
"id" : "profile-id",
"url": "http://sample-profile-url"
	…
}

For example, if you'd like to store the us-core-allergyintolerance profile, you'd use the following rest command with the US Core allergy intolerance profile in the body. We included a snippet of this profile for the example.

PUT https://myAzureAPIforFHIR.azurehealthcareapis.com/StructureDefinition?url=http://hl7.org/fhir/us/core/StructureDefinition/us-core-allergyintolerance

{
    "resourceType" : "StructureDefinition",
    "id" : "us-core-allergyintolerance",
    "text" : {
        "status" : "extensions"
    },
    "url" : "http://hl7.org/fhir/us/core/StructureDefinition/us-core-allergyintolerance",
    "version" : "3.1.1",
    "name" : "USCoreAllergyIntolerance",
    "title" : "US  Core AllergyIntolerance Profile",
    "status" : "active",
    "experimental" : false,
    "date" : "2020-06-29",
        "publisher" : "HL7 US Realm Steering Committee",
    "contact" : [
    {
      "telecom" : [
        {
          "system" : "url",
          "value" : "http://www.healthit.gov"
        }
      ]
    }
  ],
    "description" : "Defines constraints and extensions on the AllergyIntolerance resource for the minimal set of data to query and retrieve allergy information.",

For more examples, see the US Core sample REST file on the open-source site that walks through storing US Core profiles. To get the most up-to-date profiles, you should get the profiles directly from HL7 and the implementation guide that defines them.

Viewing profiles

You can access your existing custom profiles using a GET request, GET http://<your Azure API for FHIR base URL>/StructureDefinition?url={canonicalUrl}, where {canonicalUrl} is the canonical URL of your profile.

For example, use the following if you want to view a US Core Goal resource profile.

GET https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/StructureDefinition?url=http://hl7.org/fhir/us/core/StructureDefinition/us-core-goal

This returns the StructureDefinition resource for US Core Goal profile, which starts like the following.

{
  "resourceType" : "StructureDefinition",
  "id" : "us-core-goal",
  "url" : "http://hl7.org/fhir/us/core/StructureDefinition/us-core-goal",
  "version" : "3.1.1",
  "name" : "USCoreGoalProfile",
  "title" : "US Core Goal Profile",
  "status" : "active",
  "experimental" : false,
  "date" : "2020-07-21",
  "publisher" : "HL7 US Realm Steering Committee",
  "contact" : [
    {
      "telecom" : [
        {
          "system" : "url",
          "value" : "http://www.healthit.gov"
        }
      ]
    }
  ],
  "description" : "Defines constraints and extensions on the Goal resource for the minimal set of data to query and retrieve a patient's goal(s).",

}

Azure API for FHIR doesn't return StructureDefinition instances for the base profiles, but they can be found in the HL7 website.

• http://hl7.org/fhir/Observation.profile.json.html
• http://hl7.org/fhir/Patient.profile.json.html

Profiles in the capability statement

The Capability Statement lists all possible behaviors of Azure API for FHIR. Azure API for FHIR updates the capability statement with details of the stored profiles in the following forms.

• CapabilityStatement.rest.resource.profile
• CapabilityStatement.rest.resource.supportedProfile

For example, if you save a US Core Patient profile, which starts like the following.

{
  "resourceType": "StructureDefinition",
  "id": "us-core-patient",
  "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient",
  "version": "3.1.1",
  "name": "USCorePatientProfile",
  "title": "US Core Patient Profile",
  "status": "active",
  "experimental": false,
  "date": "2020-06-27",
  "publisher": "HL7 US Realm Steering Committee",

And send a GET request for your metadata:

GET http://<your Azure API for FHIR base URL>/metadata

You're returned a CapabilityStatement that includes the following information on the US Core Patient profile you uploaded to Azure API for FHIR.

...
{
    "type": "Patient",
    "profile": "http://hl7.org/fhir/StructureDefinition/Patient",
    "supportedProfile":[
        "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
    ],

Bindings in Profiles

A terminology service is a set of functions that can perform operations on medical “terminologies" such as validating codes, translating codes, expanding value sets, and other operations.
The Azure API for FHIR service doesn't support terminology service. Information for supported operations ($), resource types, and interactions can be found in the service's CapabilityStatement. Resource types ValueSet, StructureDefinition and CodeSystem are supported with basic create, read, update, and delete (CRUD) operations and Search (as defined in the CapabilityStatement), as well as being leveraged by the system for use in $validate.

ValueSets can contain a complex set of rules and external references. Today, the service only considers the pre-expanded inline codes. Customers need to upload supported ValueSets to the FHIR server before utilizing the $validate operation. The ValueSet resources must be uploaded to the FHIR server, using PUT or conditional update, as mentioned in the storing profiles section.

Next steps

In this article, you learned about FHIR profiles. Next, you can learn how you can use $validate to ensure that resources conform to these profiles.