Enabling FHIR profiles

This page explains how to import and enable FHIR implementation guides and profiles in FHIR stores.

Overview

FHIR profiles are a set of additional rules defined on top of the base FHIR specification that handle how different healthcare systems process resources. FHIR profiles can be imported and enabled in a FHIR store to ensure that all resources in a FHIR store meet specific criteria for resource structure and information captured.

You can import FHIR profiles for your FHIR store by inserting one or more structure definitions grouped into one or more implementation guides. A structure definition defines the constraints for a field in a FHIR resource. Structure definitions also reference value sets that link code systems and FHIR resources. The implementation guide enables you to use these structure definitions to validate resources so that they match the use case of your third-party software.

For example, your third-party software might need to comply with the Centers for Medicare & Medicaid Services (CMS) interoperability and patient access final rule in the US by providing a Patient Access API that is compliant to the CARIN profiles. You can import and enable the CARIN implementation guide in your FHIR store to validate the resources against the CARIN profiles. Importing and enabling implementation guides is described in the subsequent sections of this page.

After you have imported your implementation guide, you can enable it in your FHIR store for resource validation. When a resource is updated or added to the store, it is checked to see if it matches a structure definition in the implementation guide. If it does, the resource is added to the store. If the resource does not conform to the structure definitions in the implementation guide, an error message is returned and the resource is rejected.

Data validation is enforced when using the following methods:

Profile validation workflow

The following diagram shows the validation workflow for adding or updating FHIR resources:

fhir-profiles

Define your FHIR profiles

The following sections describe how to download structure definitions from your third-party software and configure an implementation guide.

Download your structure definitions

To ensure your structure definitions match your authoritative source, download the structure definitions, implementation guides, and value sets from your third-party software provider.

For example, if your system uses the Blue Button patient profile, you can download the structure definitions and implementation guide used by Blue Button.

The Cloud Healthcare API allows validation for the following type of structure definition rules:

  • slicing (on the value or pattern type)
  • min/max
  • type
  • fixed
  • pattern
  • minValue
  • maxValue
  • maxLength
  • binding

Configure your implementation guide

After you have downloaded your structure definitions, implementation guide, and value set, you must add the profiles that will be validated by the implementation guide.

To configure your implementation guide to be used in your FHIR store, complete the following steps:

  1. Open the implementation guide file you downloaded from your third-party software provider.

  2. Add the following section to include the structure definitions to be validated by your implementation guide:

    {
        "resourceType": "ImplementationGuide",
        ...
        "global": [
            {
            "type": "RESOURCE_TYPE",
            "profile": "STRUCTURE_DEFINITION_URL"
            }
        ]
        ...
    }
    

    In this example, define the following:

    • type defines the resource type.
    • profile links to the profile's source structure definition.
  3. Save the implementation guide file.

Upload your implementation guide to Cloud Storage

After you have edited your implementation guide, you must add the implementation guide, structure definitions, and value sets to Cloud Storage so that they can be used to validate resources in your FHIR store. To add the implementation guide, structure definitions, and value sets to Cloud Storage, run the following commands:

gsutil cp -r \
   PATH_TO_IMPLEMENTATION_GUIDE \
   gs://BUCKET/IMPLEMENTATION_GUIDE

Import your implementation guide

To use the implementation guide to validate profiles in your FHIR store, you must import it to your store as a resource.

The following samples show how to import your implementation guide to a FHIR store:

gcloud

To add your implementation guide as a resource to a FHIR store, run the gcloud healthcare fhir-stores import gcs command.

The following sample shows how to add your implementation guide as a resource to a FHIR store.

gcloud healthcare fhir-stores import gcs FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --gcs-uri=gs://BUCKET/DIRECTORY/*

API

curl

To add your implementation guide as a resource to a FHIR store, make a POST request and specify the following information:

  • The name and location of the parent dataset
  • The name of the FHIR store
  • The location of the implementation guide in a Cloud Storage bucket

The following sample shows a POST request using curl.

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '{
      "contentStructure": "RESOURCE_PRETTY",
      "gcsSource": {
        "uri": "gs://BUCKET/DIRECTORY/*"
      }
    }' "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:import"

If the request is successful, the server returns the response in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

PowerShell

To add your implementation guide as a resource to a FHIR store, make a POST request and specify the following information:

  • The name and location of the parent dataset
  • The name of the FHIR store
  • The location of the implementation guide in a Cloud Storage bucket

The following sample shows a POST request using Windows PowerShell.

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body '{
    "contentStructure": "RESOURCE_PRETTY",
    "gcsSource": {
      "uri": "gs://BUCKET/DIRECTORY/*"
    }
  }' `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:import" | Select-Object -Expand Content

If the request is successful, the server returns the response in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

Enable your implementation guide

To use an implementation guide resource to validate profiles, you must enable the implementation guide for validation. If you enable more than one implementation guide, these guides are applied together and a resource only has to match one profile from any enabled implementation guide.

The following samples show how to enable your implementation guide for profile validation:

curl

To enable your implementation guide , make a PATCH request and specify the following information:

  • The name and location of the parent dataset
  • The name of the FHIR store
  • The enabledImplementationGuides field set to the path to your implementation guide resource

The following sample shows a PATCH request using curl.


curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/fhir+json;charset=utf-8" \
    --data '{
      "validationConfig": {
          "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"]
      }
    }' "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig"

If the request is successful, the server returns the response in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "validationConfig": {
    "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"],
    "disableProfileValidation": false
  }
}

PowerShell

To enable your implementation guide , make a PATCH request and specify the following information:

  • The name and location of the parent dataset
  • The name of the FHIR store
  • The enabledImplementationGuides field set to the path to your implementation guide resource

The following sample shows a PATCH request using Windows PowerShell.

$cred = gcloud auth application-default print-access-token
$headers = @{ Authorization = "Bearer $cred" }

Invoke-WebRequest `
  -Method Patch `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body '{
      "validationConfig": {
          "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"],
          "disableProfileValidation": false
      }
  }' `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig" | Select-Object -Expand Content

If the request is successful, the server returns the response in JSON format:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "validationConfig": {
    "enabledImplementationGuides": ["IMPLEMENTATION_GUIDE_URL"]
    "disableProfileValidation": false
  },
}