The HSPC 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.
...
Terminology is at the heart of all FHIR resources. Because of this, we've dedicated a sandbox in the HSPC 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 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 FHIR Terminology Service is available at the following URL:
| Code Block |
|---|
httphttps://api-v5-stu3.hspconsortium.org/stu3/open |
...
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:
| Code Block |
|---|
GET httphttps://api-v5-stu3.hspconsortium.org/stu/open/ValueSet/administrative-gender |
...
Notice that we get the definition of the value set, but not the actual members of the value set. To get those, we can use the $expand operator:
| Code Block |
|---|
GET httphttps://api-v5-stu3.hspconsortium.org/stu3/open/ValueSet/administrative-gender/$expand |
...
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.
| Code Block |
|---|
GET httphttps://api-v5-stu3.hspconsortium.org/stu3/open/ValueSet/administrative-gender/$validate-code?code=female |
ResultResponse:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"resourceType": "Parameters",
"parameter": [
{
"name": "result",
"valueBoolean": true
},
{
"name": "message",
"valueString": "Validation succeeded"
},
{
"name": "display",
"valueString": "Female"
}
]
} |
Likewise, we can see that incorrect not a member of the value set by making a similar request:
| Code Block |
|---|
httphttps://api-v5-stu3.hspconsortium.org/stu3/open/ValueSet/administrative-gender/$validate-code?code=incorrect |
ResultResponse:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"resourceType": "Parameters",
"parameter": [
{
"name": "result",
"valueBoolean": false
},
{
"name": "message",
"valueString": "Code not found"
}
]
} |
...
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:
| Code Block |
|---|
GET httphttps://api-v5-stu3.hspconsortium.org/stu3/open/CodeSystem/$lookup?code=female&system=http://hl7.org/fhir/administrative-gender |
ResultResponse:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"resourceType": "Parameters",
"parameter": [
{
"name": "name",
"valueString": "Unknown"
},
{
"name": "display",
"valueString": "Female"
},
{
"name": "abstract",
"valueBoolean": false
}
]
} |
...
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:
| Code Block |
|---|
POST httphttps://api-v5-stu3.hspconsortium.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" } } ] } |
ResultResponse:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{
"resourceType": "OperationOutcome",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h1>Operation Outcome</h1><table border=\"0\"><tr><td style=\"font-weight: bold;\">INFORMATION</td><td>[]</td><td><pre>No issues detected during validation</pre></td>\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t</tr>\n\t\t</table>\n\t</div>"
},
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "No issues detected during validation"
}
]
} |
...
Let's show an example that does just this, adds a field the server isn't prepared to handle:
| Code Block |
|---|
POST httphttps://api-v5-stu3.hspconsortium.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-gener. 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.
| Code Block |
|---|
POST httphttps://api-v5-stu3.hspconsortium.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" } } ] } |
...
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:
| Code Block |
|---|
GET httphttps://api-v5-stu3.hspconsortium.org/stu3/open/StructureDefinition/fparpatient |
ResultResponse: (omitted due to size)
In the near future we will support more advanced interactions for profiled resources.
...