Configure FHIR profiles

FHIR implementation guides and profiles ensure that resources in a FHIR store conform to specific defined criteria. Some examples of implementation guides include the US Core Implementation Guide 4.0.0 and the Carin Blue Button Implementation Guide.

This page explains how to define, configure, and use implementation guides and profiles in R4 FHIR stores using the US Core Implementation Guide 4.0.0.

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. You can import and enable FHIR profiles in a FHIR store to ensure that all resources in a FHIR store meet specific criteria for resource structure and information captured.

Structure definitions and implementation guides

You can import FHIR profiles for your FHIR store by inserting one or more structure definitions grouped into one or more implementation guides. Use a structure definition to do the following:

  • Define the constraint for a field in a FHIR resource.
  • Reference value sets that link code systems and FHIR resources.

You use an implementation guide with structure definitions to validate resources so that they match the use case of your third-party software.

For example, suppose that your third-party software needs to comply with the Centers for Medicare & Medicaid Services (CMS) interoperability and Patient Access final rule in the US. Your third-party software would need to provide a Patient Access API that complies with 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 FHIR resource validation. When a FHIR resource is updated or added to the store, the Cloud Healthcare API verifies whether it matches a structure definition in the implementation guide. If the FHIR resource does match, the FHIR resource is added to the store. If the FHIR resource does not conform to the structure definitions in the implementation guide, an error message is returned and the FHIR resource is rejected.

Data validation enforcement

The Cloud Healthcare API enforces data validation 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, implementation guides, and value sets

To ensure your structure definitions match your authoritative source, you need to download the structure definitions, implementation guides, or value sets from an external source, such as FHIR.org's implementation guide registry. External sources provide a package which contains all the value sets, profiles, extensions, a list of pages, and URLs for each implementation guide.

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

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 the implementation guide uses to validate FHIR resources.

To add the implementation guide to a 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"
            }
        ]
        ...
    }
    

    Replace the following:

    • RESOURCE_TYPE: defines the resource type to which the implementation guide is applicable.
    • STRUCTURE_DEFINITION_URL: the URL to the profile's source structure definition, for example, the US Core Patient Profile.
  3. Save the implementation guide file.

    The following example shows the Patient and Organization profiles enabled for the US Core implementation guide:

    "global":[
      {
        "type":"Patient",
        "profile":"https://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
      },
      {
        "type":"Organization",
        "profile":"https://hl7.org/fhir/us/core/StructureDefinition/us-core-organization"
      },
      ...
    ]
    

Upload your implementation guide to Cloud Storage

After you have edited your implementation guide, you must upload the following files to Cloud Storage:

  • The implementation guide
  • Structure definitions
  • Value sets

After uploading, you can use these files to validate resources in your FHIR store.

To upload your implementation guide to Cloud Storage, complete the following steps:

  1. Delete all files from your implementation guide that are not used by FHIR profiles in the Cloud Healthcare API.

    For example, if you are implementing the US core implementation guide, you can delete the following files:

    • .DS_Store
    • ig-r4.json
    • openapi/.index.json
    • package.json
  2. 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_DIRECTORY
    

    Replace the following:

    • PATH_TO_IMPLEMENTATION_GUIDE: the path to the implementation guide on your local machine
    • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: the bucket and directory where you store the implementation guide in Cloud Storage

Import your implementation guide

To use the implementation guide to validate profiles in your FHIR store, import it to your FHIR store as a FHIR 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:

gcloud healthcare fhir-stores import gcs FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --gcs-uri='gs://BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY/*' \
  --content-structure=resource-pretty

Replace the following:

  • FHIR_STORE_ID: the FHIR store ID
  • DATASET_ID: the dataset ID
  • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: the location of the implementation guide in a Cloud Storage bucket

The output is the following:

Request issued for: [FHIR_STORE_ID]
Waiting for operation [OPERATION_ID] to complete...done.
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID

In this output:

  • PROJECT_ID, LOCATION, DATASET_ID: the values that you provided in the method call
  • OPERATION_ID: an identifier for the long-running operation provided by the Cloud Healthcare API

To view more details of the operation, run the gcloud healthcare operations describe command, providing the OPERATION_ID from the response:

gcloud healthcare operations describe OPERATION_ID \
  --dataset=DATASET_ID

The output is the following. If the response contains done: true, then the operation is finished. If it doesn't, then the operation is still running; wait a few seconds and then run the gcloud healthcare operations describe command again.

done: true
metadata:
  '@type': type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata
  apiMethodName: google.cloud.healthcare.v1.fhir.FhirService.ImportResources
  createTime: 'CREATE_TIME'
  endTime: 'END_TIME'
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID
response:
  '@type': type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse
  fhirStore: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID

API

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/IMPLEMENTATION_GUIDE_DIRECTORY/*"
      }
    }' "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:import"

Replace the following:

  • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: the location of the implementation guide in a Cloud Storage bucket
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID

The response is the following:

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

In this output:

  • PROJECT_ID, LOCATION, DATASET_ID: the values that you provided in the method call
  • OPERATION_ID: an identifier for the long-running operation provided by the Cloud Healthcare API

To track the status of the operation, use the operations.get method:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID
  • OPERATION_ID: the ID returned from the long-running operation

The output is the following. If the response contains "done": true, then the operation is finished. If it doesn't, then the operation is still running; wait a few seconds and then call the operations.get method again.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.ImportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse",
  }
}

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/IMPLEMENTATION_GUIDE_DIRECTORY/*"
    }
  }' `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:import" | Select-Object -Expand Content

Replace the following:

  • BUCKET/IMPLEMENTATION_GUIDE_DIRECTORY: the location of the implementation guide in a Cloud Storage bucket
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID

The response is the following:

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

In this output:

  • PROJECT_ID, LOCATION, DATASET_ID: the values that you provided in the method call
  • OPERATION_ID: an identifier for the long-running operation provided by the Cloud Healthcare API

To track the status of the operation, use the operations.get method:

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

Invoke-WebRequest `
  -Method Get `
  -Headers $headers `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID
  • OPERATION_ID: the ID returned from the long-running operation

The output is the following. If the response contains "done": true, then the operation is finished. If it doesn't, then the operation is still running; wait a few seconds and then call the operations.get method again.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.ImportResources",
    "createTime": "CREATE_TIME",
    "endTime": "END_TIME",
    "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL",
    "counter": {
      "success": "SUCCESS_COUNT"
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.fhir.rest.ImportResourcesResponse",
  }
}

Upload and import dependencies of your implementation

Before you can enable your implementation guide, you must ensure that all the guide's dependencies are uploaded and imported. Dependencies are defined by the dependsOn parameter in your implementation guide as follows:

"dependsOn":[
  {
    "id":"hl7_fhir_uv_bulkdata",
    "uri":"http://hl7.org/fhir/uv/bulkdata/ImplementationGuide/hl7.fhir.uv.bulkdata",
    "packageId":"hl7.fhir.uv.bulkdata",
    "version":"1.0.1"
  },
  {
    "id":"vsac",
    "uri":"http://fhir.org/packages/us.nlm.vsac/ImplementationGuide/us.nlm.vsac",
    "packageId":"us.nlm.vsac",
    "version":"0.3.0"
  }
]

To upload and import dependencies, follow the instructions in Upload your implementation guide to Cloud Storage and Import your implementation guide, respectively.

Enable your implementation guide

To use an implementation guide resource to validate profiles, you must enable the implementation guide. If you enable more than one implementation guide, Cloud Healthcare API attempts to validate profiles against all implementation guides. A FHIR resource only needs to match one profile from any enabled implementation guide.

The Cloud Healthcare API only validates implementation guides when you enable them. If you modify an implementation guide and enable it again, the Cloud Healthcare API validates the modified implementation guide.

If you remove an implementation guide after enabling it, the implementation guide stops taking effect.

The following samples show how to enable your implementation guide for profile validation on an existing FHIR store:

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"],
          "disableProfileValidation": false
      }
    }' "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig"

Replace the following:

  • IMPLEMENTATION_GUIDE_URL: the URL defined in the url property of the ImplementationGuide resource, for example, http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID

The response is the following:

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

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"]
      }
  }' `
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=validationConfig" | Select-Object -Expand Content

Replace the following:

  • IMPLEMENTATION_GUIDE_URL: the URL defined in the url property of the ImplementationGuide resource, for example, http://hl7.org/fhir/us/core/ImplementationGuide/hl7.fhir.us.core
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID

The response is the following:

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

Validate resources against specific profiles

The following samples show how to validate a FHIR resource for a specific profile or for all profiles defined for a FHIR store. Validating the FHIR resource lets you determine if your FHIR resource conforms to one more profiles.

To validate a FHIR resource, use the fhir.Resource-validate method.

curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @RESOURCE_FILE \
    'https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/$validate?profile=PROFILE_URL'

Replace the following:

  • RESOURCE_FILE: the location to a file containing the resource
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID
  • PROFILE_URL: the canonical URL of the FHIR profile, for example http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient for a Patient resource. There must be a StructureDefinition resource in FHIR_STORE_ID that has this URL. If you are validating the resource against the profiles you have already enabled in the store, do not provide this query parameter.
  • RESOURCE_TYPE: the resource type

If a resource conforms to the profiles, a response similar to the following is returned:

{
  "issue": [
    {
      "code": "informational",
      "details": {
        "text": "success"
      },
      "diagnostics": "success",
      "severity": "information"
    }
  ],
  "resourceType": "OperationOutcome"
}

If a resource does not conform to a profile, an error is returned with a response similar to the following:

{
    "issue": [
        {
            "code": "processing",
            "diagnostics": "Profile http://hl7.org/fhir/StructureDefinition/AuditEvent, Element 'AuditEvent.agent.requestor': minimum required = 1, but only found 0",
            "location": [
                "AuditEvent.agent"
            ],
            "severity": "error"
        }
    ],
    "resourceType": "OperationOutcome"
}

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 '@RESOURCE_FILE' `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE/$validate?profile=PROFILE_URL" | Select-Object -Expand Content

Replace the following:

  • RESOURCE_FILE: the location to a file containing the resource
  • PROJECT_ID: the ID of your Google Cloud project
  • LOCATION: the dataset location
  • DATASET_ID: the dataset ID
  • FHIR_STORE_ID: the FHIR store ID
  • PROFILE_URL: the canonical URL of the FHIR profile, for example http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient for a Patient resource. There must be a StructureDefinition resource in FHIR_STORE_ID that has this URL. If you are validating the resource against the profiles you have already enabled in the store, do not provide this query parameter.
  • RESOURCE_TYPE: the resource type

If a resource is validated for a profile, a response similar to the following is returned:

{
  "issue": [
    {
      "code": "informational",
      "details": {
        "text": "success"
      },
      "diagnostics": "success",
      "severity": "information"
    }
  ],
  "resourceType": "OperationOutcome"
}

If a resource is not validated for a profile, an error is returned with a response similar to the following:

{
    "issue": [
        {
            "code": "processing",
            "diagnostics": "Profile http://hl7.org/fhir/StructureDefinition/AuditEvent, Element 'AuditEvent.agent.requestor': minimum required = 1, but only found 0",
            "location": [
                "AuditEvent.agent"
            ],
            "severity": "error"
        }
    ],
    "resourceType": "OperationOutcome"
}