Getting more than one type of Resource back in a FHIR query

I received an interesting question from a colleague at Orion Health today:

We’re looking at the Appointment API for FHIR for some upcoming work (

The location ( of the appointment is a reference link in the API example, and we want to show that information in the list of appointments for the patient. With the current modelling I think that means we’d have one REST API call for the list and then a REST API for each appointment to get the location information. Do you know if there is any provision in FHIR for being able to “inline” the reference information for lists of content to reduce the number of HTTP requests necessary to obtain and present the information?

This is an interesting question, and one that has a number of solutions.

First – what is not: Contained resources. This was actually the subject of my very first post and you can read the details there, but briefly, contained resources are intended for situations where it is not possible to properly identify a resource – which is clearly not the situation here.

We’ll have a look at 4 possibilities (and there may be more):

  • The display property
  • The _include query parameter
  • A compartment
  • A custom service

The display property is the simplest solution. It is intended to identify what is being referenced (in this case a location resource) and is not a copy of the resource contents. The idea is that it should be enough to display in a list or some other display to the user – so would seem a good fit here. The downside is that it is populated by the resource creator, and may not have all the information that the consumer wants to display.

Next up is the _include query parameter. This allows the consumer to request that the server include other resources in the query, based on a query parameter. So the following query would ask that the server include in the response bundle the Location resources that are referenced by the Appointment resources that match the query

GET /Appointment?participant.individual={patientID}&_include=Appointment.location

The third possibility is the patient compartment. This is really a form of ‘syntactic sugar’ that allows queries to be more naturally expressed. So:

GET /Patient/{patientID}/Appointment?_include=Appointment.location

(btw – I’m not completely sure that this will work as the patient is not a single property. I’ll update the post if there are changes)

And finally, it would be possible to create a custom service – though with the options above, this doesn’t seem necessary, and these are really more intended where there is some business or task based logic to perform.

Note that only the first option is a core part of the FHIR spec – the other options depend on the server implementing them.

So there you go!

And if you are interested in the Appointment resource, now would be a good time to go and comment!

FHIR resources in specific scenarios

Taking the example of Grahames ‘Q&A’ format, the following question was asked on the FHIR List forum:

Based on what I have seen, FHIR defines a set of resources and all possible relationships between resources, but doesn’t define which/how resources should be used in a particular scenario – the latter needs to be defined as a Profile. And FHIR per se doesn’t have Profile recommendations for any scenario. Implementers need to define their own Profiles and figure out how systems interoperate on a semantics level. 

and answered by Lloyd:

Sort of.  First, FHIR doesn’t actually define all possible relationships between resources.  It merely defines the “common” ones – those deemed to be within the 80%.  Many other types of relationships are possible through the use of extensions.  (E.g. encounter is associated with a single patient in the core resource, but with extensions could support multi-patient “group” encounters, for example)
You can approach interoperability with FHIR in a couple of ways.  In one approach, you just expose everything you do as a FHIR resource and anyone who wants to consume your content can simply pick and choose from what you expose (whether as a dump in a bundle or by hitting your FHIR REStful service).  In the second approach, you expose a particular subset of content (or perhaps even enhance the capability of your system to support additional data elements) as defined by a particular profile on FHIR.  These profiles could be created by a variety of groups.  Some (e.g. a FHIR equivalent of CCDA) will likely be created by HL7 international.  Some may be produced by IHE or other international SDOs.  Some will be created by HL7 affiliates and national programs.  Some will be created by large healthcare organizations.
The creation of profiles will take time and will be driven by specific use-cases.  They don’t yet exist.  So for early adopters, you sort of have to either take the first approach or go through the process of creating your own profile, ideally with a group of like-minded early adopters.  If you’re taking the second approach, you need to identify the area of healthcare that you’re targeting, look at existing capabilities and business needs.  Inpatient care and Outpatient care look quite different.  (So does human vs. veterinary or individual vs. public health.)  That’s why your initial question of identifying the “minimum” is so challenging to answer.  The minimum depends very much on what area of healthcare you’re targeting, what problem you’re trying to solve and even what country/region you’ll be working in.

I thought it was worth sticking it up here so I can find it later! Profiles are going to be important…

Decomposing a FHIR document

Scenario 2.3 of Connectathon talks about a server ‘decomposing’ a FHIR document. This is another of those huge topics, as it is all about using the document as a ‘carrier’ for information that is used by a recipient to update their own data stores, rather than simply storing it as a ‘blob’ to be displayed to a user on request.

The issue is not so much a technical one – that’s relatively straightforward (though one of the more complex in FHIR) – but rather relates to the purpose of a document as a ‘summary at a point in time’ – or as a ‘snapshot’, rather than a mechanism to ‘transfer state’.

Read more of this post

Retrieving and rendering a FHIR document

This post is going to be a bit of an anticlimax.

Once we’ve created the FHIR document and saved it via the /mailbox entry point, then we probably want to be able to find it again at some stage (assuming that the reason we saved it was to make it available to others of course). Well, because the server created DocumentReference resources during processing, then we just need to follow the same process that we used when discussing how to retrieve CDA documents using XDS principles – i.e. query the DocumentReference end point, and then get the document using the location property of the individual DocumentReference resource.

Read more of this post

Server processing of FHIR documents: Connectathon

In this post we’re going to think a bit about how the server might process a document that it receives. This is a massive topic, and certainly not one that can be covered in a single post – or by any one individual! Apart from anything else, there are lots of different possibilities – all legitimate in specific circumstances.

This is an important concept for FHIR – it doesn’t seek to drive any particular design or architecture – rather it attempts to support how data is moved around now, and how it may be done the future. It’s up to individual implementations to decide the details, but using common ‘building blocks’.

Read more of this post

Creating a FHIR document for the January Connectathon

I had intended to talk in some detail about the Composition resource next, as this is one of the key resources for a FHIR document, but because the January connectathon is getting close I’m going to do a series of posts to directly support people attending connectathon, and wanting to experiment with the document track. I’m planning 4 posts in this series:

  • How a client would create a FHIR document (incidentally for the remainder of this series, I’m going to refer to a FHIR document just as  ‘document’, so when you see this, I’m NOT talking about CDA. Later posts will talk more about the relationship between the two).
  • How a server could process a document. There are a few possibilities…
  • How to find the document on the server later, and render it to the client.
  • A wrap up on the Composition resource and anything else left over.

I do intend to spend a lot more time on FHIR & CDA, but this should at least cover the basics.
Read more of this post

FHIR: meet #CDA

CDA (Clinical Document Architecture) is undeniably the most successful HL7 version 3 standard. It’s being used very widely around the world for representing clinical data, and is one of the core standards for many jurisdictions – like Meaningful Use in the US. Obviously, if FHIR is to succeed, then it needs to have some way of doing what CDA does now (and including all the good thinking that has gone into CDA).

Another reason to start thinking about CDA is that the next FHIR connectathon at the January Working Group Meeting next year is going to have FHIR documents as one of the themes, so it makes sense to start thinking about how this all works.
Read more of this post