The HSPC Logica Sandbox is taking steps toward supporting FHIR profile storage, retrieval and validation.  Along with this effort comes the storage/hosting of the terminology necessary to accommodate the profiling features.  In this blog post I will outline the upcoming features related to profiles, along with some examples of how these features can be useful in the development of SMART on FHIR apps.  The efforts are currently focused on support for FHIR STU3, and all examples and documentation are using this FHIR version. 

Each example request on this page can be made using the client of your choice (curl, Postman & insomnia are a few good ones). If you're using postman, you can download all example calls as a collection here: HSPC Logica Reference API - Validation.postman_collection.json.

This post covers the following:

...

Logica Sandbox as a FHIR Terminology Service

Terminology is at the heart of all FHIR resources.  Because of this, we've dedicated a sandbox in the HSPC Logica Sandbox Reference API to the storage and retrieval of terminology. This sandbox conforms the the FHIR specification of a Terminology Service, and can be used by clients to "...make use of codes and value sets without having to become experts in the fine details of code system, value set and concept map resources, and the underlying code systems and terminological principles." (source).  The HSPC Logica Sandbox Terminology Service contains more than 631,310 concepts and relationships, broken down as follows:

• SNOMED CT International RF2 (336,893 concepts)
• LOINC 1.61 (111,803 concepts)
• HL7 v2 & HL7 v3 codes backing FHIR v3.0.1

...

At the time of this blog post, the latest version of the HSPC Logica FHIR Terminology Service is available at the following URL:

https://api-v5-stu3.hspconsortiumlogicahealth.org/stu3/open

All examples use this base URL.

Use Cases

ValueSet Expansion

It's possible to list all members of a particular value set using the $expand operation.  To illustrate this, let's take a very simple value set defined by http://hl7.org/fhir/administrative-gender.  This is the Administrative Gender value set used to define the gender of the base FHIR Patient resource.  The resource itself is available making the following call:

GET https://api-v5-stu3.hspconsortiumlogicahealth.org/stu/open/ValueSet/administrative-gender

...

GET https://api-v5-stu3.hspconsortiumlogicahealth.org/stu3/open/ValueSet/administrative-gender/$expand

...

You can read more about the $expand operation here.

ValueSet Validation

Another useful operation on the ValueSet resource is $validate-code.  This allows you to ask, in a single call, if a particular code is part of a given value set.  This can save some client side logic and bandwidth when developing apps.  Using the same value set as above, we can check if female is a valid code with the following command.

GET https://api-v5-stu3.hspconsortiumlogicahealth.org/stu3/open/ValueSet/administrative-gender/$validate-code?code=female

...

https://api-v5-stu3.hspconsortiumlogicahealth.org/stu3/open/ValueSet/administrative-gender/$validate-code?code=incorrect

...

You can read more about the $validate-code operation here.

Code lookup

Another useful task when developing apps is retrieving details about a particular code. Say you have access to the code value, but not the display value.  To look up the display you can make the request:

GET https://api-v5-stu3.hspconsortiumlogicahealth.org/stu3/open/CodeSystem/$lookup?code=female&system=http://hl7.org/fhir/administrative-gender

...

You can read more about the $lookup operation here.

Advanced Use Cases

In addition to the basic use cases we've walked through above, the FHIR spec outlines several advanced features such as subsumption testing, batch validation and translations.  As work progesses progresses on the HSPC Logica Terminology Service we will provide documentation on how to use these, in the meantime you can read about them here.

Resource Validation & Profiles

Profiling is a broad term in FHIR, but generally it is the process adding additional restrictions to base FHIR resources.  These additional restrictions often include restricting properties to a particular value set or making properties required (editing cardinality). This type of profiling can increase interopability and is encouraged in the FHIR ecosystem. 

These profile specifications are expressed using the StructureDefinition resource, providing a machine readable interpretation of the profiled resource.  All base FHIR profiles have a corresponding StructureDefinition resource and the FHIR spec also defines profiled versions of some resources to accomodate common use-cases.  Further, it's common for organizations to partner in creating their own StructureDefinitions which expand on the base FHIR defintions in order to accomodate the sharing of data around a particular domain.

The HSPC Logica Terminology Service contains all base FHIR StructureDefinition resources (205) and we are working on support for FPAR profiled resources (141).  The FPAR resources are stored in the HSPC Logica Terminology Service, however some value set data is incomplete at this time. 

Use Cases

This StructureDefinition information is utilized by the server to implement validation functionality. This is exposed with the $validate operation which can be performed at the resource instance level.  Validation uses the HL7 "InstanceValidator", which is able to check a resource for conformance to FHIR profiles (StructureDefinitions, ValueSets, and CodeSystems), including validating fields, extensions, and codes for conformance to their given ValueSets.

Validating a FHIR Resource

Let's use the validation functionality to validate a base FHIR Patient resource, based on the basic patient example in the FHIR docs.  The request would look like this:

POST https://api-v5-stu3.hspconsortiumlogicahealth.org/stu3/open/Patient/$validate
--- REQUEST BODY ---
{
  "resourceType": "Patient",
  "identifier": [
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/v2/0203",
            "code": "MR"
          }
        ]
      },
      "system": "urn:oid:1.2.36.146.595.217.0.1",
      "value": "12345",
      "period": {
        "start": "2001-05-06"
      },
      "assigner": {
        "display": "Acme Healthcare"
      }
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Chalmers",
      "given": [
        "Peter",
        "James"
      ]
    },
    {
      "use": "usual",
      "given": [
        "Jim"
      ]
    },
    {
      "use": "maiden",
      "family": "Windsor",
      "given": [
        "Peter",
        "James"
      ],
      "period": {
        "end": "2002"
      }
    }
  ]
}

...

This operation can be useful in ensuring that no data is lost in the creation of the resource.  If we were to add a field which isn't defined on the server (not contained in the StructureDefinition), it is acceptable behavior for the server to discard this field and save the remiander remainder of the data. To avoid this, your application can call the validate endpoint before each save or update if there is any doubt about the data integrity. 

...

POST https://api-v5-stu3.hspconsortiumlogicahealth.org/stu3/open/Patient/$validate
--- REQUEST BODY ---
{
  "resourceType": "Patient",
  "incorrect": "field",
  "identifier": [
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/v2/0203",
            "code": "MR"
          }
        ]
      },
      "system": "urn:oid:1.2.36.146.595.217.0.1",
      "value": "12345",
      "period": {
        "start": "2001-05-06"
      },
      "assigner": {
        "display": "Acme Healthcare"
      }
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Chalmers",
      "given": [
        "Peter",
        "James"
      ]
    },
    {
      "use": "usual",
      "given": [
        "Jim"
      ]
    },
    {
      "use": "maiden",
      "family": "Windsor",
      "given": [
        "Peter",
        "James"
      ],
      "period": {
        "end": "2002"
      }
    }
  ]
}

...

A slightly more advanced use of the $validate operation would be to verify that property values are a member of the correct value set.  Let's return to using our example value set, administrative-genergender.  The FHIR Patient resource specifies that the Patient.gender field MUST be one of the values in this value set. Let's post a validation request containing the value "incorrect" for gender and see what happens.

POST https://api-v5-stu3.hspconsortiumlogicahealth.org/stu3/open/Patient/$validate
--- REQUEST BODY ---
{
  "resourceType": "Patient",
  "gender": "incorrect",
  "identifier": [
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/v2/0203",
            "code": "MR"
          }
        ]
      },
      "system": "urn:oid:1.2.36.146.595.217.0.1",
      "value": "12345",
      "period": {
        "start": "2001-05-06"
      },
      "assigner": {
        "display": "Acme Healthcare"
      }
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Chalmers",
      "given": [
        "Peter",
        "James"
      ]
    },
    {
      "use": "usual",
      "given": [
        "Jim"
      ]
    },
    {
      "use": "maiden",
      "family": "Windsor",
      "given": [
        "Peter",
        "James"
      ],
      "period": {
        "end": "2002"
      }
    }
  ]
}

...

You can read more about the $validate operator as well as validation in general here.

Querying StructureDefinition Resources

If you are interested in examining the StructureDefinition which defines certain profiles, you can do so by accessing the /StructureDefinition endpoint directly.  For example, the following request retrieves the FPAR profiled patient resource:

GET https://api-v5-stu3.hspconsortiumlogicahealth.org/stu3/open/StructureDefinition/fparpatient

...

In the near future we will support more advanced interactions for profiled resources.

Conclusion

This sums up our first steps towards supporting terminology and profiling on the HSPC Logica Sandbox.  In the future we hope to support and document use-cases such as profile-specific validation (us-core, hspclogica, fpar, etc) as well as add more terminology sets to our collection.

...