FHIR Documents (and other stuff)

I had an email from a company which had a number of really good questions about exposing data through FHIR, so I thought I’d write a post about it rather than just replying directly as it may be of interest to others (and also gives others the opportunity to disagree with me 🙂 )

So the context is an organization that looks after patients in a ‘residential’ setting (kind of like a hospital) that is collecting healthcare information about its residents and wishes to share that information with other organizations (subject to privacy/consent of course) such as their usual General Practitioner .

The first question was about where to put the ‘textual’ information in a resource – should it be the specific elements (like description or summary) that appear on many resources – or should it be the ‘text’ element that almost all resources have (Bundle is an obvious exception).

The resource.text element is described in the spec, and it specifically calls out that its purpose is to be able to be displayed to a human, and it should represent the structured contents of the resource in a clinically safe manner. For example, the narrative for an AllergyIntolerance could contain the allergen, the reaction, its severity and so forth. But not all implementations will just display the narrative – often they will display a rendering created from the structured data, as that allows a display to be consistent. For example, imagine a table of allergies  – you’d want to put the allergen in one column and the reaction in another rather than requiring the user to read the narrative to get the list of allergies.

So – in general – you’re going to put the information in both places – the structured elements to support a UI laid out in a specific manner, and in the text element to support direct displays of the resource to a user. Of course, this will vary from resource to resource and between implementations as it will depend on the actual use case. The text might also be to a different level of detail.


Next up was a question about consult notes. This doesn’t have a simple answer right now. There’s a ‘clincialImpression’ resource, but this is very immature and it’s not yet clear where it will be used.

Then there’s also the question of how much of the data is textual, and how much is structured. For example, you probably want the medications and observations to be able to be extracted from the notes by the recipient (to be able to update their internal records for example – or to be able to draw a graph).

We’d likely think of a clinical note as a Document – a summary at a point in time that should be persisted in the clinical notes, and that leads us to the Composition resource. Somewhat analogous to the CDA header, it has places to put the author of the note, the type of note, date it was written and so forth.

It also has sections, that allow the textual note to be represented in an ‘ordered’ fashion to a viewer – separating out the reason for the consultation from the observations made during the consultation for example. Think of a paper Discharge Summary from a hospital and the sections you see in those as an example. Each section in the Composition has a code that identifies what the section is about (maybe reason for consultation) and a text element where the human readable text goes. This text is important as it is used to render the overall document into a human readable form (along with the text from the Patient resource and the Composition itself – see the formal description of this).

But, of course, all this (apart from the Patient – we’ll come to that in a moment) is just the human readable content. It’s fine for showing to a human, but what if you want components like the medications or observations to be extracted by the recipient?

The way this is done is that the Composition resource is actually inside a special container resource – the Bundle – along with any other resources you might want to include. Certainly the Patient will be there, but there can also be any other resource that makes sense. The diagram below shows how this is organized.


The Bundle is the container (which is why it doesn’t have a text element itself) and inside that container is the Composition (it has to be the first one), the Patient and all the other resources you want to include. There are references from the Composition section/s to those resources (sometimes via a List resource, though that is entirely optional) and most them will also have a reference to the Patient (remember that in FHIR references are explicit – unlike CDA you can’t assume that any given resource ‘belongs’ to the patient just because it is in the same bundle).

One resource that is not in the diagram above is the Encounter. It’s likely that we would want this resource as well, and there’s a specific element on Composition that references it.

There’s a lot more to say about documents in FHIR – but hopefully this describes the basics.

The last question was about how to decide which of the elements in the resources should be populated. The answer, unfortunately, is ‘it depends’. It depends on the structured information you have available in the source system, how well coded it is, what is important to include in a given use case and so forth.

My personal opinion is that you should include as much structured/coded data as you have – but it’s not a simple matter to do so as matching the data you have to the elements in a resource can be tricky (especially when you have data for which there is no obvious place to put it). Technically we call this process ‘profiling’, and it’s important as it helps establish consistency between applications (amongst other things).

So – that’s a (very) brief answer to the questions!

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.

4 Responses to FHIR Documents (and other stuff)

  1. Rene Spronk says:

    When discussing text we should however mention that sometimes the text part may be richer in detail than the underlying structures (this is denoted by a type code on that text, “additional”) – which in some scenarios is preferred over structured data capture (see https://annals.org/aim/fullarticle/2089368/clinical-documentation-21st-century-executive-summary-policy-position-paper-from ), and in other cases the text may be generated from the structured data (type code “generated”).

    Aiming for structured content instead of text is NOT always the proper way to go. In future we may even have NLP which is powerful enough to just deal with text (and derive any structure from it) – but that may take a while. In general I’ve learned to be very careful in balancing the necessity for a certain amount of structure, and the flexibility of text (as e.g. required by a clinical note).

Leave a Reply

%d bloggers like this: