Extending fixed code sets – revisited

We’ve talked previously about the options available when you are building a FHIR interface (a façade) to an existing system, and there is a resource property with a fixed code set whose values are not the same as the ones in the existing system.

One of the options we discussed was to map the codes in the existing system to those in the spec, using extensions where existing codes ‘meant’ the same – just added more detail.

For example – in our existing system we have the concept of ‘for review’ prescriptions – the prescription has been issued, but local policy dictates that the prescription must be reviewed by a pharmacist (perhaps this must occur if the patient is on many medications) so it is not yet ready for dispensing/administration.

The MedicationPrescription.status field has ‘on hold’ as one of its values which is close enough for us to use. After all, a MedicationPrescription in a ‘for review’ status is, effectively on hold until the pharmacist has approved it (or not – as the case may be).

So we have a solution – but we are losing some data. Clients that only understand the spec won’t be affected, but clients that are familiar with our existing system (like the one we’re building) could use that in the display to give the user more information.

So, let’s build an extension.

Remember that there are 2 parts to an extension:

•        It is defined in a Profile (in the <extensionDefn> element)
•        It is used in an instance using the <extension> element (or <modifierExtension> if it modifies the meaning.

So we have a few decisions to make.

First, is this a modifierExtension? Well, we’ve already determined that it is safe to represent a MedicationPrescription in the status of ‘for review’ as if it were in the status of ‘on hold’, so it can be an ordinary extension (which is a relief – modifierExtensions are to be avoided if possible).

Next, what’s the scope of this extension? What resources can it be applied to, and does it only apply to specific properties of that/those resource/s? I suspect that this is always going to be a bit more of an art than a science – ideally we want to have reusable extensions (and I have a post planned on that), but we do need to be careful that it ‘makes sense’ to do so.

In this case, we’re going to assume that ‘for review’ really only makes sense for a MedicationPrescription, and further that it only makes sense to use it in the MedicationPrescription.status property (after all – a ‘reason for prescription’ of ‘on hold’ doesn’t make a lot of sense).

So, now that we’re got an extension scoped to a single property of an instance of MedicationPrescription, how are we going to represent that in the instance? And what will the definition look like in the profile?

I find it easier to start with the instance.

Recall that an extension in an instance can apply:

•        to the whole instance (in which case it is at the top of the instance)
•        to a specific property (in which case it is represented with the property)
•        or to a datatype (in which case it is represented with the value)

Clearly this is the second option – the extension will be with the property.

So instead of:

<status value="on hold"/>

we will have

<status value="on hold">
  <extension url="wwww.fhir.orionhealth.com/Profile/nma#original-code">
    <valueCode value='for review'/>
  </extension>
</status>

Not too hard! Note the url in the extension:

•        the extension is defined in the Profile to be found at wwww.fhir.orionhealth.com/Profile/nma
•        it has the name of ‘original-code’
•        it is of the datatype ‘code’.

Now for the definition.

We’ve already decided on the Profile and the name of the extension – how do we define it (including the set of possible values) – and, in particular, how do we state that it should only be used for the MedicationPrescription.status property?

Well, to define the set of possible values we create a ValueSet that defines the codes (they will almost certainly be in our own local system) and then create a binding to that valueset from the extensionDefn element in Profile

To indicate that the extension should only be used by the MedicationPrescription.status property, we simply set the value of extensionDefn.contextType to resource, and the context value to MedicationPrescription.status property.

So the complete definition will look like this:

<extensionDefn>
    <code value="original-code"/>
    <contextType value="resource"/>
    <context value="MedicationPrescription.status"/>
    <definition>
        <short value="Detailed status codes used by the HIS"/>
        <formal value="These are the mode detailed codes used by the HIS system for MedicationPrescription status and mapped to the standard codes."/>
        <min value="0"/>
        <max value="1"/>
        <isModifier value="false"/>
        <binding>
            <name value="Valid values for original code"/>
            <isExtensible value="false"/>
            <referenceResource>
                <reference value="ValueSet/nmaStatusCodes"/>
            </referenceResource>
        </binding>
    </definition>
</extensionDefn>

One thing we haven’t done is to define the actual mappings between the two code systems – that will be up to the application to do so. However, there is a proposed resource – the concept  map – that we could use for this, which would make the mappings explicit. And incidentally, this is one of the reasons that we created the ValueSet as a separate resource, rather than just containing it in the profile. Containing resource seems easier, but does significantly reduce options downstream so should only be done when there are no other options.

So, we’re good to go!