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'/>

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:

    <code value="original-code"/>
    <contextType value="resource"/>
    <context value="MedicationPrescription.status"/>
        <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"/>
            <name value="Valid values for original code"/>
            <isExtensible value="false"/>
                <reference value="ValueSet/nmaStatusCodes"/>

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!



About David Hay
I'm a Product Strategist at Orion Health, Chair emeritus of HL7 New Zealand and co-Chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the new FHIR standard.

5 Responses to Extending fixed code sets – revisited

  1. grahamegrieve says:

    it would be good to think a little more about the descriptions, for instance, how they’d appear in a dialog like the one described here: http://hl7.org/implement/standards/fhir/modifier-extension-warning.png

    That dialog is for modifier extensions, of course, but it’s expected that a system that doesn’t know the extension can retrieve the definition, and produce some human readable representation. In the case of what you have above, it would be:

    “The specific HIS codes: for review”

    Something like

    “Detailed status code: for review”

    would be more informative for a user

    • David Hay says:

      Good point – though the message the user would see would relate to the fact that this extension defined codes – rather than specific codes…

      and btw – in making the change I realised that I had the binding wrong! It is to a valueset not a profile of course…

  2. Also good to suggest creating extensions in a generic way. In your example, I’d have probably defined this as a “translation” code. That’s much more generic and can be leveraged in a lot more situations (and is thus more likely to get recognized)

    • David Hay says:

      very true. I was overly focussed on finishing the example… ‘translation’ extension might qualify for an HL7 level extension perhaps? Then you could create a ‘use case’ profile that referred to that extension using the ‘definition.mapping’ to refer to the conceptmap resource to define the specific mappings?

      Creating consistent and re-usable extensions is something we’re grappling with here at Orion at the moment…

  3. Pingback: FHIR Profiles: an overview | Hay on FHIR

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: