Resource References, v2 Messages and Locations

There’s been an interesting conversation today on the Implementers chat about the various ways that one resource can reference another, and there are a number of possibilities! They are all variants of the Resource Reference so, lets’ take a quick look at that before we dive into the details.

The resource reference element has 2 properties:

• The reference, which is a string
• The display – also a string.

and both properties are optional.

The overall idea is that the reference points to the resource being referred to – which could be contained within the referring resource, could be in a bundle with the referring resource or could be on another server somewhere in the FHIR ecosystem.

The purpose of the description is so that a system displaying the ‘referring’ Resource doesn’t have to go and retrieve the ‘referred to’ resource in order to be able to display something. (btw It’s not the same as the text element of the referred-to resource – it’s just a summary).

So when creating a resource that needs to refer to information in another, we have a number of options available to us:

• We could place all the text in the display element and forget about a separate resource
• We could create a contained resource, and have the reference point to that. (Probably with the description as well, though we will have the contained resource ‘inside’ the main one and so easily accessible)
• We could locate the resource we want to refer to (assuming it exists as a separate entity) and have the reference point to that. We’d almost certainly want to include a display as well, so we don’t have to go and retrieve it when rendering it.

The actual conversation came up in the context of message mapping between HL7 Version 2 messages and FHIR – and specifically the Encounter.location property, which is a reference to a resource of type Location, so let’s use that as our example.

Suppose that we are mapping an ADT-01 message, and need to decide what to do with the location which is in the PV1-3 field, and is of data type ‘PL’ (Note that that’s a v2 datatype – not FHIR.)

The PL data type is a complex one, with the following components (in brackets is the v2 datatype of each subtype)

• Point of Care (IS)
• Room (IS)
• Bed (IS)
• Facility (HD)
• Location Status (IS)
• Person Location type (IS)
• Building (IS)
• Floor (IS)
• Location description (ST)

(IS is a user coded field, HD is a hierarchical Description and ST is a string. IS would be an Identifier in FHIR, and HD probably an Identifier as well – I’m not a v2 expert, so will happily accept correction…)

The big question to ask is how much of this information do I want/need to keep?

If we’re really only interested in being able to display the location as text on the screen, then we can create a suitable string – eg Bed 2, Ward 4 Middlemore Hospital – and put it in the reference.display property, leaving out the Reference.reference property. Easy.

But what if we want more detail than that? What if it’s important to be able to extract out the more detailed elements at some later date – perhaps a patient in a bed is discovered to have a communicable disease and we want to find all patients who have been in that bed? (This raises an interesting discussion about search, but let’s not go down that hole just yet). Or the message is being consumed by a support application – like the dietary department – which needs to know the precise location

In this case we have to model the location as a separate resource (and we’ll talk about that in a moment), but we still have to decide whether to use a contained or an independent resource.

The answer is, of course, ‘it depends’.

In the examples above, there are real advantages in having a separate external resource for each location, and having our Encounter reference that. Of course, this does add complexity during the mapping as we have to search for an external Location in order to find the right one – so we need to be sure that the effort is worth it. It may be that we’re more interested in being able to format a nice table on the screen with Hospital, Ward and Bed being in separate columns – and in that case a contained resource will be just fine.

All of these options are legitimate in FHIR – it’s the implementers choice. (Oh, and incidentally this does point out some of the responsibilities of a FHIR client – unless you have an agreement with the server, there might be different places where information may be, it’s up to the client to look for it. There are other client responsibilities as well, such as looking for extensions (especially Modifier extensions – perhaps we’ll discuss these in a later post).

And finally – assuming we have decided to have a real Location resource, how well does it map to v2? Actually, it’s a wee bit complicated. The Location resource only covers a single location – so the bed, ward and hospital are all separate locations. Locations can be ‘part of’ other locations, so you can have a bed, which is part of a ward, which is part of a hospital – you need 3 Location resources (in this example) to represent the single v2 datatype! (and it can get more complex than that. (One of the commenters in the skype chat called it a ‘recursive reference dance’ – which is rather nice I thought !)

Here’s one example using contained locations. Note that we’ve modelled the Ward as a Location instead of an Organization as suggested in the spec, as we treat the Ward as a physical place rather than an organizational unit – this is, of course, open to debate..

<Encounter xmlns="http://hl7.org/fhir">
    <contained>
        <Location>
            <id value="bed"/>
            <name value="Bed 1"/>
            <physicalType>
                <coding>
                    <system value="http://hl7.org/fhir/location-physical-type"/>
                    <code value="bd"/>
                </coding>
            </physicalType>
            <partOf>
                <reference value="#ward"/>
            </partOf>
        </Location>
    </contained>
    <contained>
        <Location>
            <id value="ward"/>
            <name value="ward 4"/>
            <physicalType>
                <coding>
                    <system value="http://hl7.org/fhir/location-physical-type"/>
                    <code value="ro"/>
                </coding>
            </physicalType>
            <partOf>
                <reference value="hospital"/>
            </partOf>
        </Location>
    </contained>
    <contained>
        <Location>
            <id value="hospital"/>
            <name value="Good Health Hospital"/>
            <physicalType>
                <coding>
                    <system value="http://hl7.org/fhir/location-physical-type"/>
                    <code value="bu"/>
                </coding>
            </physicalType>
        </Location>
    </contained>

    <!-- Rest of encounter stuff here -->
    <status value="in-progress"/>
    <location>
        <location>
            <reference value="#bed"/>
            <display value="Bed 1, Ward 4, Good Health Hospital"/>
        </location>
    </location>

</Encounter>

 

In this model, the ward is simply the contained location with a physicalType of ‘ro’ (we may want to further refine the valueset as ‘ro’ is probably not specific enough for our purposes…)

There are alternatives, such as using naming conventions for the ID of locations, but I suspect that this will be one area of focus as the work on mapping from HL7 v2 progresses…