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):

Great question! Three points of background to start:
1.  The specific example you linked to is broken — it’s misusing FHIR’s “contained” mechanism and we decided in needs to be fixed.  See this discussion for more context.
2.   In general, FHIR’s “contained resources” mechanism is a real area of confusion for implementers — so thanks for raising these questions.  We definitely need to work on the documentation.  But please have a read through Contained Resources if you haven’t seen it already.
3.  As described in the link above, “Contained Resources” are designed to solve a very specific problem: they are meant to be used when “the content referred to in the resource reference does not have an independent existence apart from the resource that contains it”.  To say that a different way: Contained Resources are not meant to be used simply as a way to serialize content inline.  (I personally think this is a very subtle distinction for most implementers to observe, and as such it’s a technical risk for the FHIR spec.)
Now to answer your question 🙂
When one resource “points to” (references) another, this is done in FHIR via a “resource reference” element that looks (in XML) like:
          <type value=”Medication”/>
          <reference value=”___REFERENCE GOES HERE___”/>
If the medication you’re pointing to is explicitly hosted by the FHIR server as a “Medication Resource”, then reference/@value of the reference is just a link like: “medication/@12345“.  But if the medication you’re pointing to isn’t “externally identified” (i.e. isn’t hosted by the FHIR server because we don’t have enough information about it as an independent entity), then FHIR provides a mechanism to embed its contents directly in the MedicationPrescription. That’s called a “Contained Resource.”
For contained resources, the reference/@value is an XML element id like “#someMedicationId” — and to resolve it, you look for a “contained”Medication element (with id=”someMedicationId”) inside the MedicationPrescription/contained.

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!


About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

12 Responses to FHIR Contained Resources

  1. Pingback: Getting more that one type of Resource back in a #FHIR query | Hay on FHIR

  2. Pingback: Hay on Fire | Hay on FHIR

  3. Pingback: Setting the Hay on Fire « Health Intersections Pty Ltd

  4. Pingback: Clinical Scenarios in FHIR: Adverse reaction | Hay on FHIR

  5. Pingback: FHIR and XDS – Submitting a document from a Document Source | Hay on FHIR

  6. Pingback: Creating examples in FHIR | Hay on FHIR

  7. Pingback: Responsibilities of a FHIR client | Hay on FHIR

  8. Pingback: Orders in different servers | Hay on FHIR

  9. Pingback: Managing the Medication List in SNapp, part 1. | Hay on FHIR

  10. Mark Sternig says:

    We are working with a client to build a custom FHIR-based API that will allow them to get a Patient (or list of patients) with additional related resources such as the patient’s Account, Encounters, Coverage, etc. It would be great to combine/contain the related resources so that the client doesn’t need to make several API calls to get all related resources. Since “contained” resources should only be used when they cannot be accessed directly, do you have any suggestions on how to best represent this information?

  11. Lloyd McKenzie says:

    The _include, _revinclude search parameters and the $everything operation are all mechanisms intended to help with this issue. Sending a ‘batch’ Bundle containing multiple queries is also an option. ‘contained’ resources as a transport mechanism is not an appropriate choice.

Leave a Reply

%d bloggers like this: