Dev’s on FHIR — Care Connect FHIR External References

Reference consistency is not the most sexy topic but it can help health care move to interoperability standards by saving development effort, improving profile validation and end to end testing.

In this post we will explore FHIR Messages. FHIR Messages are generally self contained

  • e.g. they contain all the resources a consumer would need to process a message
  • i.e. the Bundle is self referential

The rest of this post looks at some options for FHIR References.

If you wish to understand more about FHIR Reference please see this article The choices of References on NHS Spine

Photo by Muneeb Syed on Unsplash

Self contained resources can lead to large bundles, e.g. a Message Bundle based on DocumentReference may need to exchange a limited set of metadata:

  • Patient: NHS number, name, gender and date of birth
  • Author — Doctors: GMP or GMC code plus name
  • Custodian — Organisation: SDS code and name

The DocumentReference Bundle is likely to contain these resources:

  • DocumentReference
  • Patient
  • Practitioner
  • Organization

The bundle can be “quite” large and contains a lot of information the consumer does not require. Especially as the metadata makes use of national code systems. These code systems often contain the identifier/code or have the ability to look it up (e.g. for SDS/ODS Organisation identifiers using the ODS API).

FHIR has a number of options we can use to reduce the size of the message bundles and still send over the required information, these are:

  1. Reference by Logical URI
  2. FHIR R3/STU3 Reference by Identifiers
  3. Hybrid

FHIR does not exist in isolation and we will also discuss the use of identifiers in HL7 v2.

1. Reference by Logical URI (Logical Identifier)

One way is to use resolvable reference. The example below comes from National Record Locator Service (NRLS) and uses a RESTful interaction, it shows both a logical uri reference and a actual reference:

Both the author and custodian can be resolved by following the reference, i.e. if you follow this link you find it is Leeds Teaching Trust

but the reference to the Patient by NHS Number doesn’t (it’s logical — it may become resolvable in the future)

A drawback of this approach is I need to know a map of CodeSystem uri’s and reference uri’s. So I would need to know reference uri for corresponds to the CodeSystem for SDS/ODS identifiers e.g. :

Leeds Teaching Trust ODS Identifier entry

Similarly for NHS Numbers we have:

From a technical point of view, if I have a reference within a Bundle I should follow it. When I find a reference beginning withurn:uuid: the resource is within the bundle, if not I should follow the reference. Which in the case of the NHS number it will fail with a 404 as the reference is logical.

Edit: When we use resolvable references we tend to use the ‘Logical Id’ of the resource and so they inherit characteristics of Resource Identity:

  • implementations SHOULD NOT assume that the identity of a resource is always resolvable to a literal server
  • references may change

2. FHIR R3/STU3 Reference by Business Identifiers

STU3 also allows the a different approach via the use of identifiers:

So the example custodian reference used above would become

<system value="" />
<value value="RR8" />
Tip: Recommend always including the display as this may save prevent an extra call just to retrieve this basic information and the JSON/XML is more readable

Likewise the reference to the Patient would become

<system value="" />
<value value="9876543210" />
<display value="Mr Joe Blogs" />

In this example the fact that 9876543210 is the NHS Number is less ambiguous.

I mentioned earlier I should be able to resolve these references by looking them up but how do I know where to look them up?

3. Hybrid (RESTful External References)

This post originally set out to discuss using FHIR Messaging, in particular the number of resources that would be contained with a simple FHIR Message (e.g. Document Feeds). However FHIR RESTful has related issues exist, e.g.

  • Condition references Patient but my system does not hold data to build a complete Patient resource (it only knows the English NHS Number and a few demographics e.g. name).
  • Condition references Practitioner but I only have the business identifier and so not enough data to build the resource.

These can be resolved but not on the server generating the resources. So we could use external references, e.g.

Although we have mentioned resolvable uri’s can be transient, in a RESTful exchange you would not expect the referenced resource to change between call and resolution attempt. It is possible though that the caller can’t access the given url (fire-walled, trust agreements, etc) or the caller uses a different server for resolution (in the example, trusts may use resolve NHS numbers locally and apps outside England may use a different uri). How do we cater for them, in the example the business identifier is encoded in the uri but how would we know that? A solution is to additionally include reference by business identifiers (see above), e.g.

The reference is getting larger but as a developer of a consuming system it very helpful.

  • If I just want to know the name of the patient, it’s present and so I don’t need to resolve the reference.
  • If I just need to know the NHS Number, it’s also present so I don’t need to resolve it (and I also know it is an English NHS Number).
  • If I do need to resolve it, I can either use the NHS Number or follow the reference.
Tip: In a large number of scenarios the presence of display name of the and/or business will prevent extra RESTful calls.

HL7v2 and FHIR Compatibility

Current interfaces used in healthcare interoperability like HL7v2 can be converted into FHIR and vice versa. Examples like the ITK HL7v2 Message Specification make high use of ODS/SDS references (but not for Patient). In (ADT^A01 Inpatient admission) extract below references to NHS Number, SDS/ODS and practitioner codes are highlighted in bold.

PID|1||3333333333^^^NHS||SMITH^FREDRICA^J^^MRS^^L|SCHMIDT^HELGAR^Y|196512131515|2|||29 WEST AVENUE^BURYTHORPE^MALTON^NORTH YORKSHIRE^YO32 5TT^GBR^H||+441234567890||EN|M|C22|||||A|Berlin|||GBR||DEU
PD1|||MALTON GP PRACTICE^^Y06601|G5612908^Townley^Gregory^^^Dr^^^GMC
NK1|1|SMITH^ALBERT^J^^MR^^L|1|29 WEST AVENUE^BURYTHORPE^MALTON^NORTH YORKSHIRE^YO32 5TT^GBR^H|+441234567890||||||||||1|196311111513||||EN
PV1|1|I|RCB^OBS1^BAY2-6^RCB55|13||| ^Darwin^Samuel^^^Dr^^^GMC|G5612908^Townley^Gregory^^^Dr^^^GMC|C3456789^Darwin^Samuel^^^Dr^^^GMC|300||||19|||||2139^^^VISITID|||||||||||||||||||||||||201010201716
DG1|1||N39.3^Stress Incontinence^ICD10||201010090900|A|||||||||1|C3456789^Darwin^Samuel^^^Dr^^^GMC|D|N|201010090900
PR1|1||ZZS4^Colonic examination^OPCS4||201010202056|D|34|||||C3456789^Darwin^Samuel^^^Dr^^^GMC|C3||N39.3

This could be converted into a FHIR message consisting of:

  • MessageHeader (MSH)
  • Encounter (PV1)
  • Patient (PID)
  • RelatedPerson (NK1)
  • AllergyIntolerance (AL1)
  • Condition (DG1)
  • Procedure (PR1)

The references to Practitioner, Organisation and Location would all be by ‘Business Identifier’. Following the same convention in FHIR messaging would be preferable for compatibility reasons.


Reference consistency matters as this can save development time, improve profile validation and help health care move to interoperability standards. In many cases HL7 FHIR will complement HL7v2 and it is important these standards can work together. HL7v2 shows a clear pattern on how we should reference the Entities which can help to reduce the size of a FHIR Message.

So the recommendation is for

1. Entities to be referenced by identifier
  • Practitioner (when appropriate)
  • Organization
  • Location
2. Individuals should be included references (i.e. the resource is included in the message).
  • Patient
  • RelatedPerson

For both RESTful and Messaging exchanges, it would be desirable to include in the resource reference:

  • Logical reference
  • Business identifier
  • display name

Thoughts and opinion welcome @KevinGMayfield. Get in touch with us INTEROPen Ryver, UK Zulip or by contacting