Clinical resources in FHIR

I gave a talk on Clinical resources in FHIR at the recent seminar in Melbourne, which was actually a bit more work to prepare than I had anticipated. I’ve given a few FHIR talks, but generally they were about the fundamentals of FHIR or more technical training, and this was intended to be aimed more at a clinical audience.

Read more of this post

isModifier and mustSupport in FHIR

There’s been a discussion on the FHIR list about ‘mustSupport’ and ‘isModifier’ that I think I now understand – but I’m going write down for when I forget later! (Most of the wording below has been directly copied from comments by Grahame or Lloyd either in the spec or in comments on the list)

First, what  do they mean.


From the spec:

If true, the value of this element affects the interpretation of the element or resource that contains it, and the value of the element cannot be ignored. Typically, this is used for status, negation and qualification codes. The effect of this is that the element cannot be ignored by systems: they SHALL either recognize the element and process it, and/or a pre-determination has been made that it is not relevant to their particular system.

Only the definition of an element can set IsModifier true – either the specification itself or where an extension is originally defined. Once set to false, it cannot be set to true in derived profiles. An element/extension that has isModifier=true SHOULD also have a minimum cardinality of 1, so that there is no lack of clarity about what to do if it is missing. If it can be missing, the definition SHALL make the meaning of a missing element clear.

 Then Lloyd commented:

We mark something as a modifierExtension not because a human might care about it, but rather because it might impact what a computer is doing with existing data.  If you’ve got a decisions support system that’s driving off of data elements and your extension changes the interpretation of any of those, then you need to flag to the decision support engine “don’t try to process this data unless you understand the extension”.  So long as the meaning of existing data is unchanged, it doesn’t matter how clinically relevant/important the data is, it’s not a modifierExtension.  (Data perceived to be clinically important/relevant by the originator should however be highlighted prominently in the narrative.)

 And Grahame added:

What makes something is a modifier is not that it might modify care, but that it might modify the understanding of existing data elements. This should be understood in a narrow sense, not an expansive one – it’s really about “is it safe to use the existing data without knowing the additional information”, not “would knowing the additional information influence my course of action in interpreting the data”.


From the spec

If true, conformant resource authors SHALL be capable of providing a value for the element and resource consumers SHALL be capable of extracting and doing something useful with the data element. If false, the element may be ignored and not supported.

“Something useful” is context dependent. This flag is never set to true by the FHIR specification itself – it is only set to true in profiles, and when the profile sets it true, it SHALL describe what it means for applications to support the element. In general, the question is what would a reasonable observer expect of a system that explicitly claims to “support” this element?.

And Lloyd added:

The purpose of “mustSupport” is for use in situations such as national program created profiles where they want to leave an element as “optional” (data won’t always exist and thus no need to include the element in all instances), but want to state that implementers playing in a particular space (and thus declaring conformance to the profile) must *support* that element (e.g. be able to capture, display, process, store, etc.)  The specific meaning of mustSupport would need to be declared by the Profile.  As an example, the panCanadian v3 profile for Patient identifies “date of death” as being “required” in our v3 message specification.  That means minOccurs=0, conformance=required.  Systems don’t have to send it, but they must be capable of sending, capturing and storing it.  With FHIR, we’d accomplish the same thing by setting minOccurs=0 and mustSupport=true in our profile.


mustSupport is meaningless at run time.  mustSupport only matters at conformance time.  Someone publishes a profile that says “If you want to comply with my profile (and thus get paid ‘meaningful use’ $$ or be eligible to respond to this RFP or be allowed to be installed in my hospital, etc.), you must support this element.  You declare that you support the profile in a contract or an RFP response or whatever.  It’s entirely possible that the profile will never be referenced in an instance at all.  (And if it were, it shouldn’t cause any change of behavior.)

 My Comments

Both mustSupport and isModifier flags are recorded in the profile resource.

isModifier can apply both to core elements (i.e. elements of resources that in the spec) and also to extensions. In some cases the base specification has marked elements as isModifier – eg MedicationPrescription.status. If you do define an extension in a profile, and mark it as ‘isModifier=true’, then when an actual resource instance contains this extension, it must use the modiferExtension element, rather than the usual extension element. This makes it really explicit to a consumer that this extension can modify the meaning of the resource.

Remember that all the core FHIR resources also have a profile attached to them. You can retrieve these from either Grahames or Ewouts server by a query against the profile resource – eg or

Updated: Grahame commented that all profiles are provided directly from the spec

mustSupport can apply to both elements and extensions, but are only set in a profile – i.e. the base specification has no elements marked as mustSupport. A resource instance will use an ordinary extension element (unless it it isModifer too of course).

Hope that all makes sense!

FHIR: A question of identity

One thing that comes up frequently for people new to FHIR is the concept of a resource identity – and I have a great deal of sympathy with this as I also had a lot of trouble getting my head around exactly what this is.

The identity of a resource is one of the fundamental concepts in REST – and in FHIR. In fact the way that you refer to a resource is via its URI – the Uniform Resource Identifier. It is a way of unambiguously locating or specifying the resource: if you have the URI then you can find and refer to it – for example being able to state unambiguously to which patient a particular condition refers.

What seems to trip people up in healthcare is the similar business concept of a patient identifier, like a Medical Record Number (MRN) or in New Zealand the National Health Identifier (NHI) and which is often called a patient ID. Despite the similar sounding (identical!) names, they are quite different.

  • The resource ID refers to the location of a resource (any resource) on a particular server (or at least the ‘external address’ – it’s up to the server where and how  it’s physically stored, but it does agree to always refer to that resource from that place). Further, the resource ID is unique only on that server – it’s not transportable between servers.
  • The MRN is actually an identifier from a registry/system of some sort – and identifies the person/patient for the business purpose of healthcare delivery. In healthcare, this functionality is often supplied by a ‘Master Patient Index’ (MPI) that has all sorts of sophisticated algorithms to help to resolve issues like two identifiers referring to the same person.

So FHIR also has these 2 concepts:

  • The resource ID (specific to a server) that every resource MUST have. If a copy of the same ‘thing’ is stored on different servers, then they will have different IDs, but the ID  will never change on a given server. It’s kind of like a primary key in a database – except that the primary key will change if a record is migrated to another database, which means that the location on that server would change, which means that it is no longer the same resource. A sequential counter or GUID that doesn’t change and stays with the record might be a better choice. The resource ID is not a property of the resource – it is held outside of it.
  • A specific resource (like Patient) CAN have one or more identifier properties that refer to some external system or registry. FHIR doesn’t have any particular requirements of an identifier, only that you can specify the ‘system’ within which the identifier is unique – eg a passport, or a drivers license are equally valid identifiers. And, an identifier can change for a given resource.

Another way to think of the difference is that the resource ID is a ‘system’ level ID – it locates resources and allows one resource to reference another. Change the ID and it becomes a different resource. An identifier is about how humans categorize things – including other humans – and can change.

When a resource is copied from one server to another (maybe it is in a bundle, and the recipient server wants its own copy), then it will receive a new ID on the new server and so is a different resource (there is a different URI that refers to it). However, if there is an identifier property on the resource, then that will remain the same so a consumer of the resources will know that they are actually pointing to the same real world entity – eg a patient.

There is more discussion on resource identity in the spec here, and about the identifier here. And I’ve talked before in this blog about REST in general, and using the ID to manipulate resources.

In this blog I try to consistently refer to a resource ID as its ‘ID’, and a specific identifier property as ‘identifier’

Makes sense?

A REST primer – FHIR style – part 1.

In this post I’m going to talk a little about REST – REpresentational State Transfer – in the context of FHIR. The FHIR specification goes into some detail about how REST and FHIR work together, so go there for more details.

As mentioned in a previous post, FHIR works across many different interoperability paradigms, but REST is the best established at this point in time – and by far the easiest to use (as you will see). It’s the one used by companies such as google, amazon and twitter to provide access to their services (as well as 37 signals – which was the original inspiration for FHIR).

Despite the complicated sounding name, it’s actually quite simple – in fact, it’s the way the web works. The term REST was first used by a chap called Roy Feilding – one of those uber-smart guys that defined many of the basic web protocols that we take for granted today. In a PhD dissertation, he took some of the basic web concepts, and described an ‘architectural style’ that took advantage of those concepts in an easy to use way. (sounds like the goals of FHIR – right)?

The basics are really quite simple.

  • REST is built on top of the HTTP protocol – the same protocol you use when requesting a web page in your browser. HTTP (short for HyperText Transfer Protocol) is simply a set of rules that both server and client (in this case a browser) use to exchange data over the web. HTTP is a ‘request/response’ protocol – you make a request (which can contain data), the server responds and that’s it.
  • REST thinks in terms of resources, each of which has an identity by which it can be manipulated. This is the URI (Uniform Resource Identifier), and uniquely specifies the location of a resource. It is specific to a particular server.
  • When manipulating resources, there are a fixed number of methods that you can use. The ones that are of particular interest to FHIR include:
    • GET – retrieve a particular resource based on its URI (server location + id). FHIR uses the GET method both to retrieve a single resource, and to perform a search which could potentially return multiple resources.
    • POST – create a new resource at a specified endpoint. In REST the server will assign an id, and the combination of server location and id becomes the URI for that resource.
    • PUT – update an existing resource. The client that is executing the PUT needs to know the URI of the resource (which, in FHIR, means that they know the id of the resource as well as the server where it is stored). In FHIR, this will create a new version of the resource.
    • DELETE – remove a resource. Again the URI must be known. It is recommended (though not mandated) in FHIR that a copy of the resource is maintained, and potentially reachable using a version aware read, and the history by a history request, but a plain GET should not return the resource any more. (It will, however, return a status code telling the user that a resource was deleted – read on!)
    • OPTIONS – this is a ‘special’ method in FHIR, that is directed to the root of the server, and returns a conformance resource that informs the client what the capabilities of the server are. I’ll write about this some other time – it’s actually quite useful, though not necessary to know for normal operation.
  • When a server responds to an HTTP REST request, it processes the request according to the method and its internal business logic, and then returns a response to the client. The response has a number of parts to it:
    • The body of the response is what the client is requesting from the server – generally in response to a GET request. Most of the other methods do not return a response. (Note: in the current version of the spec they actually do – but that will be removed soon).
    • The server always returns a status code – which informs the client what the outcome of the request was – did it succeed, or did it fail – with some further details about the nature of the outcome. The status code is a number, which has a well defined meaning within the HTTP protocol. FHIR defines an operationOutcome resource, which the server can use to give the client detailed information about any failure.
    • Both the request and the response can contain headers. These provide extra information about the request or response to assist the server or client to properly process the transaction. Examples include:
      • Both request and response use the Content-type header to tell the other party whether a resource is in xml or json format.
      • A client will use the Accept header to tell the server what format (xml/json) it would prefer to get back when making a GET (though the server is not obligated to honor this)
      • The server will use the Location header to tell the client the URI of a newly created resource
      • And so on.

    Well, that’s enough background – lets actually do something in FHIR. Let’s get a patient resource from one of the on line FHIR test servers.

    Paste the following command (which is actually a URI) into your browser:

    What this does is to instruct your browser to make a GET request to the specified URI, and display the results in your browser. You should see an XML version of the Patient resource that has the id of 4165431. Simple – eh?

    Dissecting the instruction a bit:

    • HTTP:// – specified the HTTP protocol
    • – the endpoint on the Public HAPI server that responds to FHIR requests
    • Patient/ – specified that the operation was to be on the Patient resource
    • 4665431 – specified the patient with the id of 4665431.

    A couple of notes:

    • I needed to know what the Id was. It was fairly safe in this case because the public HAPI server is a test server with some fixed resources, and unless someone else deletes that resource it should be available (try another number if that happens). You could use this technique to retrieve any type of resource from any FHIR server – provided that you knew the Id – and passed any security mechanisms.
    • The only thing you can do through the browser (at least this way) is to issue GET requests.
    • For better results (and to use the other verbs) use a REST client like POSTMan
    • I haven’t talked at all about security.

    In the next post I’m going to delve into REST a bit further – how to search for resources if you don’t know the id, how to change existing ones or create new one. And, if there is time, how to do queries across resources – e.g. all the conditions associated with a specific patient.

    BTW – if the link above doesn’t work, then try  What you’ll get is a collection of Patients rather than a single one. 

What is FHIR (and why should I care)?

In my self-appointed role as ‘FHIR evangelist’ (some would say ‘FHIR Fanatic’) at Orion Health and HL7 New Zealand I’m often asked ‘what is FHIR, and why should I care’. Rather than trying to explain each time, I’m going to write a short post here, so I can refer people to it, rather than trying to remember all the good points at the time.

So, what is FHIR?


  • FHIR (Fast Health Interoperability Resources) is the latest interoperability standard from HL7, following on from Version 3. (Strictly speaking it builds on rather than replacing v3, but also pulls in ideas from other organizations such as openEHR or IHE).
  • FHIR has the fundamental concept of “Resources”, where a resource is the basic unit of interoperability – the smallest ‘thing’ that makes sense to talk about – such as a Patient, a Condition (Problem) or a Practitioner.
  • Resources have a number of common characteristics, including:
    • A small number of ‘core’ properties that most (80%) of systems currently support. Each property is a specific datatype (although some resources allow more than one datatype to be used for a property)
    • A standard extension mechanism that allows implementers to add new properties in a safe and discoverable way. (This is the lesson of version 2)
    • An ‘identity’ by which it can be saved, located & retrieved
    • A human readable component that summarizes the data in the resource for a human to read (This is the lesson of CDA).
  • Resources can be re-used across interoperability paradigms. You could receive (or save)  a resource via a REST service, and then package it in a Message or include it in a Document.
  • There is a built in versioning system. Each resource can have multiple versions, and there are mechanisms to retrieve the history of a specific resource, and/or a specific version.
  • The specification itself is on-line, and fully hyperlinked. You can link through from resource, to a property, to the datatype of that property. Where a particular terminology or code set has been defined for a property, you can hyperlink to that dataset. (Terminologies are a bit more tricky to link to).

Why should you care?

  • FHIR has been build with the needs of the Implementer in mind. We try to be as simple as possible, but no simpler.
  • This extends to the use of connectathons, where developers can try out ideas before being included in the specification.
  • Standard tooling can be used.
  • You can use XML or JSON representation.
  • Each resource has a specific validation schema / schematron (again, a lesson from CDA)
  • All the artifacts (including the schema) are automatically built using a build process (similar to a software build). This significantly improves the overall quality of the specification.
  • Each resource has multiple examples that shows how the resource can be used. The resources themselves are ‘round-tripped’ from XML -> JSON ->XML and validated as part of the build process to ensure accuracy.
  • FHIR (especially the JSON representation) is great for mobile development
  • There are number of open-source clients to make it even easier to use
  • There are also some test servers to test your work out on.
  • Lots of other people are looking very closely at FHIR

An example of a Patient resource is shown below. This one also has an embedded picture within it.

<?xml version="1.0" encoding="UTF-8"?>
 <Patient xmlns="">

   <!-- Each extension is at the top of the resource. This one points to the embedded photo of Donald -->
     <url value=""/>
       <reference value="#pic1"/>
       <display value="Duck image"/>

   <!-- Here is the Human readible part...-->
     <status value="generated"/>
     <div xmlns="">
       <p>Patient Donald DUCK @ Acme Healthcare, Inc. MR = 654321</p>

   <!-- Contained elements allow an 'anonymous' resource to be embedded. In this case the image -->
     <Binary id="pic1" contentType="image/gif">adads -- rest of b64 encoded image here....</Binary>

   <!-- The elements below this are the 'core' elements of the resource -->
     <use value="usual"/>
     <label value="MRN"/>
     <system value="urn:oid:"/>
     <value value="654321"/>
     <use value="official"/>
     <family value="Donald"/>
     <given value="Duck"/>
       <system value=""/>
       <code value="M"/>
       <display value="Male"/>
   <active value="true"/>

Well, I hope I’ve answered the question of “what is FHIR and why should you care”. Feel free to leave any comments below.


In the beginning…

Looking back over the past year, I’ve given a number of talks on FHIR. I’ve also been lucky enough to have been sponsored by my employer – Orion Health – to speak at a number of overseas conferences, including CHIMA in China, and HIMSS Asia-Pac in Hong Kong.

In most of these presentations I’ve started by giving an overview of the HL7 Interoperability standards, and where FHIR fits into that family, including why it was developed in the first place. Sounds like a good topic for a blog post!

The first version of HL7 (which was actually  version 2) was developed around 1987 by Ed Hammond in response to a need to share health information within a healthcare enterprise. The name “HL7” stands for ‘Health Level 7’ – where the 7 refers to the 7th layer (applications) of the OSI model.

I asked Ed why the version was 2 and not 1 – he replied that there was a initially a version .5 that was more of a scoping version, and a version 1.0 that was demonstrated at a HIMSS conference. This was more what we would call a DSTU (Draft Standard for Trial Use) today. Version 2.0 was the first version that made it “into the wild”.

The standard become widely used – largely due to it’s relative simplicity, but also because it allowed individual implementers to define ‘extensions’ to the standards in the form of ‘Z-segments’ which allowed them to share data that had not yet been formally defined in the main HL7 standard.

However a number of issues developed over the years.

  • Implementers produced a proliferation of overlapping Z-segments that could only be understood by the the parties that defined them – usually a single sender and recipient.
  • People started using the defined fields within segments for unexpected purposes – for example if their particular implementation did not need to use a particular field for the defined purpose, they ‘re-used’ it for something else.
  • Individual segments got more and more fields added – with any of them optional

This led to the saying the ‘Once you’ve seen one HL7 v2 implementation –  you’ve seen one HL7 v2 implementation!’  Semantic interoperability – being able to communicate ‘meaning’ was really restricted to individual sets of trading partners who would agree in advance what the meaning of these ‘extended’ fields was.

In response to these issues, HL7 started work on version 3 around 1995. Version 3 created a common  ‘Reference Information Model’ and a standardized development process, from which the various HL7 artefacts were derived. It was an ambitious programme (and not without critics) as it attempted to provide a mechanism to share any clinical information without necessarily having to agree in advance what that information was. The first release was in 2005.

However, with the exception of CDA (Clinical Document Architecture), version 3 didn’t really take off. It was used in Canada (Health Infoway) and the UK (Connecting for health), but most people continued to use v2 for messaging needs, and CDA for documents (in fact – people started using CDA where a messaging approach was really required – as a document standard, CDA does not support workflow). There were a number of reasons for this.

  • Using v3 properly is hard. It is a very abstract standard, and you need to understand quite a bit about it to work with and extend the standard.
  • Development of new business  ‘domains’ was slow – 3-7 years to become ‘normative’ was not unusual.
  • All of the tooling to develop and publish standards needed to be custom built.
  • It has been said that v3 is designed to suit the needs of the modeller, not the implementer. For example, with the exception of CDA, there is no standardized XML schema across all v3 messages.
  • In most cases v2 continued to do the job – why change?
  • The world had moved on – real-time connectivity and the standards that support that (HTTP, XML, JSON, REST, ATOM and many others) were commonplace, as was the concept of “API’s” to support the electronic exchange of information.

Recognizing these issues, the HL7 Board commissioned a ‘fresh look’ at HL7 in 2011. The mandate was ‘What would we do if we were starting with healthcare interoperability from scratch today’? The team noted that:

  • HL7 doesn’t really have a ‘modern’ standard for, say, mobile application or cloud developers.
  • There was a lot of good work and thinking in v3 – it was just hard to get at it.
  • V2 remains enormously popular, yet is based on old technology (but it is simple to understand, and does support extensibility). A migration path is needed.
  • CDA is popular because it supports implementers:
    • There is a standard XML schema – that common tools can manipulate
    • It supports ‘incremental semantic interoperability’ through human readible text elements
    • There is a concise specification, a number of well defined Implementation guides with reference implementations and schematron validators
    • There were many implementations of CDA (and CCD – which is a type of CDA) internationally, and a body of knowledge that built up around it.
    • You don’t need to understand v3 to use it!
    • but – it does not support workflow, and it is designed for the Document paradigm.

Grahame Grieve (from Australia) had already been talking about a different approach – Resources For Healthcare – on his blog (health Intersections) and this was used as the basis to develop what was to become FHIR (Fast Health Interoperability Resources). It was presented at the May Working Group meeting in Vancouver, and quite literally was the star of the show. FHIR had arrived!