Extending a required ValueSet Binding

One of the issues we come across quite a lot at Orion Health is where we are creating a read FHIR interface to an existing data service with elements in the FHIR resource that are coded and have a ‘required’ binding to a ValueSet (which means that you must only use one of the values in the ValueSet) – and the data we are mapping from has a different value. AllergyIntolerance is a particular culprit in this regard as it has a number of required bindings, but it has come up most recently in MedicationStatement.status where we have values that are different to the ones in STU2 – the FHIR version we are using.

Now, the solution is actually quite straight forward. In the resource instance you choose the value from the ValueSet that most closely matches the missing one, and then create an extension on that element (not at the resource root) that contains the actual value you want to represent.

For example the following snippet shows how we want to represent ‘stopped’, and the closest match is ‘completed’

{
  “resourceType”:”MedicationStatement”,
  …
  "status": "completed",
  "_status": {
    "extension" : [
       {
         "url": "http://fhir.hl7.org.nz/dstu2/StructureDefinition/ms-status",
         "valueCode": "stopped"
       }
    ]
  }
 …
}

(Note that in JSON the extension is the element name preceded by an underscore – see the spec for more details)

Update: a previous version of this post had the dataType of the extension as ‘string’ (valueString). However, as the original datatype is ‘code’ valueCode makes more sense…   

In this way, a consumer that doesn’t understand our extension can still safely process the resource, while one that does can potentially do specific actions.

So now we need to create the Extension Definition (a StructureDefinition resource of course) – and it will be a coded value, so we’re also going to need a ValueSet with the set of possible codes.

To figure out how we do that, we need to take a short digression into terminology.

The following diagram is taken from the most recent version of the spec (at the time or writing), and shows the relationship between the core terminology resources:

Looking at these resources:

• The Code System is ‘master list’ of codes (or concepts) that we can use – for example SNOMED or LOINC or one of the HL7 defined ones.
• The ValueSet is the sub-set of those codes from that CodeSystem for our particular context of use (in this case the MedicationStatement resource)
• The Element Definition will be part of our Extension Definition and will ‘bind’ the element to the ValueSet.

(It’s actually a wee bit more complex than that as a single ValueSet can reference content from more than one Code System – a minor detail…)

So what we need to do for our Extension Definition is to first create the ValueSet, and then create the Extension Definition which will refer to that ValueSet. But wait – where will the ValueSet get its values from? In our case we are defining values that aren’t in an existing Code System. Unfortunately the answer is slightly different in STU2 and STU3.

• In STU2 we define the codes directly in the ValueSet resource (using a unique url that we create as the ‘system’).
• In STU3 we first create a CodeSystem resource that contains the codes we want, and then refer to that CodeSystem from the ValueSet.

Why was it changed? Well, it allows for better re-use of the CodeSystem we create – if we need to use it again in a different ValueSet, then we don’t need to duplicate all the codes, which is always a hassle. (And incidentally, this is one of the big advantages of the FHIR approach – we’ll get a much better standard at the end, even if it is extra work for the early adopters).

So let’s look at STU-2 first.

The ValueSet will look something like this:

{
 "resourceType": "ValueSet",
 "url": "http://hl7.org/fhir/ValueSet/ms-code ",
 "name": "Extra values for MedicationStatement.code",
 "codeSystem": {
    "system": "http://fhir.hl7.org.nz/CodeSystem/ms-code",
    "concept": [
      {
        "code": "stopped",
        "display": "Stopped",
        "definition": "Indicates that the medication was stopped before it was completely given"
      }
    ]
 }
}

Notes:

• The url property is the ‘cannonical url’ that is globally unique and identifies this particular ValueSet.
• The codeSystem element contains the new codes/concepts
• The codeSystem.system element is another canonical url that will identify the codesystem (rather than the ValueSet)
• concept is an array of the actual code/concepts that are in this ValueSet.
• The example is not complete – only pertinent fields have been included, and there’s only a single concept.

And the Extension Definition will have a binding to this ValueSet using the binding.valueSetUri field (so it doesn’t matter where the ValueSet is actually stored). If we do know the actual server where the ValueSet is stored, and are confident that it will be available forever then we could use the binding.valueSetReference field, but the uri seems safer to me.

Now let’s discuss the situation in STU-3

Overall the principle is exactly the same, the only difference is that the definition of the code system has been pulled out to its own resource, and the ValueSet then refers to that resource rather than defining it inline. This is exactly how we refer to other code systems like SNOMED & LOINC, so much more consistent than the STU2 way.

Here what the CodeSystem would look like:

{
"resourceType": "CodeSystem",
"url": "http://fhir.hl7.org.nz/CodeSystem/ms-code",
"concept": [
 {
       "code": "stopped",
       "display": "Stopped",
       "definition": "Indicates that the medication was stopped before it was completely given"
   }
]
}

and here’s the ValueSet:

{
"resourceType": "ValueSet",
"url": "http://hl7.org/fhir/ValueSet/example-inline",
"name": "Extra values for MedicationStatement.code",
    "compose": {
       "include": [
           {
               "system": "http://fhir.hl7.org.nz/CodeSystem/ms-code "
           }
       ]
   }
}

Notes:

• In the ValueSet, the compose.include element has a ‘system’ value only – meaning that the entire CodeSystem with the url of http://fhir.hl7.org.nz/codesystems/ms-code is included. If we wanted to, we could specify a subset of those code/concepts – just as we normally do.
• The examples are incomplete.

So there you go. Easy as…