FHIR Contained Resources

I’ve been meaning to write a blog for some time.

In fact I started one a year or so back which I let drop (a common occurrence I suspect). I’ve also had some pressure from my colleagues at Orion Health (Thanks Mark & Sandra) and it was them that suggested this title – due to my passion for the new HL7 FHIR standard. When I mentioned the possible title to Grahame Grieve (the originator of FHIR), he started laughing – apparently in the old days when convicts were deported from England to Australia for relatively trivial offenses, word came back that Australia was a rather better place to live than England was at the time, so being deported there was a *good thing*. However, there was a fine line between being deported, and being hung (which is a *bad thing*). Turns out that the safest way was to set a hay stack on fire – and then ensure that you were caught. So the title has stuck…

But what really prompted me to get going was this post on the HL7 FHIR list about contained resources. It was answered by some of the FHIR experts – Josh Mandel and Lloyd MacKenzie, and I though that this is the sort of information that needs to be easily locatable on the web as it is a question that is likely to be asked many times as people start to implement fhir. The FHIR specification is very readable, and there is a section on contained resources, but it is always helpful to have other information to help explain the concept.

We are also encouraging people to use stack overflow, but not everyone will use that site.

So without further ado – what are contained resources in FHIR?

First from Josh (slightly modified):

And then from Lloyd

When you have a resource reference, the resource it points to can be conveyed in one of 3 ways:

1. It can be left on the server to be retrieved by the client when /if they wish.

2. It can be bundled with the referencing resource as part of an atom feed.  (This can happen in messages, documents, ‘batch’  REST submissions and in query responses where the query used _include to request that the referenced resource be included in the bundle.)

3. The resource can be contained inside the referencing resource.  This approach is used when the referencing resource ‘owns’ the referenced resource.   The referenced resource can’t be queried or accessed on its own and can’t be referenced from any other resource.  This is intended for use when the resource can’t be resolved to an existing resource and there isn’t enough information to create a unique, resolvable resource instance.

In the case of medication in a prescription, containment will be pretty common because medications aren’t necessarily fully specified and compound recipies are often considered to be part of the order rather than stand-alone.

That said, you can’t count on medication always being contained.  Nor should you choose to contain resources just for ease of transport.

And finally from me

Do note the format of the reference element:

• If it refers to an external reference on the same server, then it can be a relative reference like medication/@12345
• If it refers to an external reference on a different server, then you need the full url – eg http://fhir.myserver/medication/@12345
• In either of the above examples you can have the full history – eg medication/@12345/history/@3 – to refer to a specific version of the resource
• If it is a reference to a contained resource, then use the # symbol – eg #12345  – where the id is the id on the contained element, and doesn’t include the resource type

So, I do hope that this is useful to someone in the future. It is a bit ironic that my first post should essentially be plagiarism, but I promise to be more original in the future!

cheers…