#FHIR and Character encoding in URLs

One issue that is causing confusion for FHIR implementers is the question of what characters need to be escaped in an http: URL. The general shape of an http: url is

http://[server name]/[path]?[name]=[value]&[name]=[value]


  • http://acme.org/fhir/Patient/1
  • http://acme.org/fhir/Patient?gender=male&address-postalcode=12345

For a FHIR implementer, we will assume that there is no need to do escaping in the [server name] and [path] fragments (there’s possibly corner cases where you might need to, but these are either rare or non-existent in the FHIR community). On the other hand, there’s certainly specified circumstances where the parameter value is specified to contain characters that may need escaping. For example, one possible URL is:

GET fhir/ValueSet?url=http%3A%2F%2Fhl7.org%2Ffhir%2FValueSet%2Fclinical-findings

In this URL, the characters : and / have been encoded using % encoding, as specified in the http standard. (See the encoding table here, but I prefer this tool for normal use). But what characters do you have to encode like that? well, that’s where it gets a little slippery. Quoting from wikipedia:

When a character from the reserved set (a “reserved character”) has special meaning (a “reserved purpose”) in a certain context, and a URI scheme says that it is necessary to use that character for some other purpose, then the character must be percent-encoded.

The key thing here is that which characters have to be encoded depends on which characters have special meaning. In a parameter value, the character ‘&’ has special meaning – so you have to escape that. Escaping the rest is optional. So this URL is equal to the one above:

GET fhir/ValueSet?url=http://hl7.org/fhir/ValueSet/clinical-findings

as is this:

GET fhir/ValueSet?url=%68%74%74%70%3A%2F%2F%68%69%37%2E%6F%72%67%2F%66%68%69%72%2F%56%61%69%75%65S%65%74%2F%63%69%69%6E%69%63%61%69%2D%66%69%6Ed%69%6E%67%73

These are all valid, and servers should support all the possible variants. Generally, we try to keep away from specifying characters that need escaping; they just cause problems for everyone. Yes, they’re resolvable, but no, we don’t want people losing time over them, so we don’t, e.g. define parameter names with ‘=’ in them.

So, as a client, you only need to escape in a very few places. There’s one place in the FHIR spec where this escaping arises as an explicit issue, we we need escape with in the value of the parameter itself. This edge case is discussed explicitly in the spec.

Note that there’s one other case where you absolutely have to escape the parameter values: if they contain characters not in the ASCII code range of characters 33 – 127 – typically, spaces or unicode characters.

#FHIR is 5 years old today

Unofficial FHIR project historian Rene Sponk has pointed out that it’s exactly 5 years to the day since I posted the very first draft of what became FHIR:

Five years, on August 18th 2011 to be precise, Grahame Grieve published the initial version of FHIR (known as RFH at the time) on his website. The date of the initial version was August 11th – which is the reason for this post today. Congratulations to all involved for helping to create a success – FHIR has gained a lot of interest over the past few years, and a normative version will be published in the near future.

Wow. 5 years! Who would have thought that we’d end up where we are? I really didn’t expect much at all when I first posted RfH back then:

What now? I’m interested in commentary on the proposal. If there’s enough interest, I’ll setup a wiki. Please read RFH, and think about whether it’s a good idea or not

Well, there was enough interest, that’s for sure.

And it’s rather a coincidence, then, that on the 5th anniversary of the first posting, I’ve just posted the ballot version for the STU 3 ballot.  This version is the culmination of a lot of work. A lot of work by a lot of people. Lloyd Mckenzie and I have been maintaining a list of contributers, but so many people have contributed the specification process now that I don’t know if we’re going to be keep even a semblance of meaningfulness for that page. I’ll post a link to that version soon, with some more information about it

p.s. Alert readers will note that the blog post announcing RfH was dated Aug 18th – but it was first posted August 11th.

Principles of Health Interoperability SNOMED CT, HL7 and #FHIR (Edition 3)

I’m pleased to announce that the 3rd edition of “Principles of Health Interoperability” is now available. Tim Benson wrote the first 2 editions, with coverage of V2, V3, CDA, and SNOMED CT, and he asked me to join with him for the 3rd edition, and provide a section on FHIR.  I’m really glad to say that it’s finally come to fruition, and the book is now available.

Dr John Halamka very kindly wrote a foreword for the book. Quoting from it:

Health Interoperability is a must read for policymakers, technology leaders and industry implementers.    The book distills thousands of pages of standards into the essential information you need to know.  The addition of the Fast Healthcare Interoperability Resources (FHIR) make the 3rd edition even better than the 2nd edition.   FHIR will enable an ecosystem of apps, which layer on top of existing EHRs, reduce the cost of interfacing and accelerate innovation.

If you are looking for the definitive resources on the latest techniques to implement content, transport and vocabulary interoperability, look no further than this book.   It will be a centerpiece of my own bookshelf

As far as I know, this is the first published book that covers FHIR. Well done to Tim for bulldozing me across the line. I’ll be bringing a pen to the next HL7 meeting for signatures…


Furore DevDays: Premiere #FHIR meeting in Europe

I’ve just booked my flights for DevDays:

FHIR Developer Days is an event for implementers, whether new to FHIR or with previous experience, to test and develop their FHIR implementations in a collaborative environment. FHIR DevDays offers a chance to work with the specification surrounded by others doing the same thing, side by side with experts to answer any questions. The hackathon and educational tracks are divided into beginner and advanced tracks. The beginners track for the hackathon will feature a round table with tutorials and intensive coaching.

DevDays is the best FHIR event in Europe each year, and this year, the list of subjects, and the thought leaders, has grown again. Even if you’re not committed to FHIR, that’s an amazing group of people to engage with at a single meeting.

You should be there! I’ll see you there…




Question: Apple CareKit and #FHIR


I am very new to FHIR and now i am trying the find out equivalent resource for  Apple carekit data. I think i can use FHIR Careplan & Goal for the CareKit data. Is that right?


I’ve not done any work with CareKit, but Apple suggested I talk to Seth Berkowitz at BIDMC, who says:

CareKit is a set of UI and database components that provide a framework to display careplans, collect patient generated data, provide insightful feedback to and from patients via their iOS phones.  By leveraging simple game mechanics and Apple’s design ethos, the UI components of CareKit help motivate patients to comply with their daily medications and activities as part of their care plan.  The assessment component streamlines the collection of subjective and objective data from patients using the phone as middleware. Objective data collection is facilitated through HealthKit, which is Apple’s centralized database on it’s phones that facilitates the sharing of objective health metrics in between apps.  The last component of carekit is a communication module that helps patients share their care plans and results with friends, family, and medical professionals

BIDMC we are integrating our CareKit app directly into our homebuilt EHR so that the app becomes a direct conduit of prescriptions and orders from doctor to patient, and patient generated data from patient to doctor.  Although our short term goal is to benefit our own population of patients, we share Apple’s long term vision of widely disseminating these engaging apps.  To that end, we are trying to leverage FHIR APIs as much as possible to serve as the connections between our EHR and the App.  The hope is that Apps like this serve as a “carrot” to promote more widespread adoption of the FHIR standard.  Our two main APIs using FHIR are a medication search bundle and CarePlan resource.  Our medication bundle leverages our institutions participation in the Argonaut projects

CareKit encompasses several functions which pose potential FHIR interfaces for data download and upload.  To date, my group has focused on leveraging FHIR for data download in order to populate the CareKit “CareCard” (a patient check list of careplan activities) and Carekit “Assessment” or subjective and objective measurements collected on the phone. An overarching question that we’ve been trying to solve is how encode UI / implementation specific data fields within the appropriate FHIR schema.  For example, a careplan activity in carekit is displayed with a title, a subtitle, and more detailed instructions.  For each careplan activity I’ve been using the following mapping

  • Title: activity.detail.code.text
  • Subtitle:  activity.detail.goal (either display or description of a contained resource)
  • Instructions: activity.detail.description

For quantitative measurements that are collected on the phone through the HealthKit database, I define an “observation” activity within the careplan.  The activity.detail.code.coding array defines a LOINC codable concept which is then mapped to Apple’s internal reference system for various physiological measurements (heart rate, blood pressure, daily sodium intake, etc)

Finally, we define certain alert conditions that may prompt a message to the patient after a measurement is obtained.  These alerts are implemented as an extension to the activity.detail.goal.  The extension includes a valueQuantity which is the threshold that triggers the alert and a referenced Flag resource which is the alert prompt to the user.

There’s much more to be done to build an end-to-end CareKit FHIR interface, but that’s what we’ve been working on so far.

Thanks to Seth and also to Pascal Pfiffner, who’s been a trail blazer with regard to FHIR use on iOS (and who maintains the FHIR Swift reference implementation).

Seth noted that with the careplan resource, it feels like they’re pushing the limits of how the careplan is being used in practice – and indeed, that’s true. There’s a lot of active projects using FHIR as the format for exchange underlying shared care/ collaborative care projects that involve the patient, and their various care teams: family, professional, social etc., and this is a new – exciting! – area where there’s not a lot of established knowledge, culture, and practice for us to fall back on. So implementers should expect more change in this area than in the well established ones (patient management, diagnostics, medication administration, billing).

Question: Binding choices


A question regarding “Standard” codes vs. Customized codes: To my understanding, if I want to exchange FHIR resource, any property in that resource can be filled by either of the following options:

  • Using the standard clinical coding system for relevant clinical properties (for example, SNOMED CT code for MedicationOrder>Medication>code
  • Using the HL7 FHIR administrative coding system for relevant administrative properties (for example, http://hl7.org/fhir/ValueSet/medication-order-status for MedicationOrder>Status)
  • Using customized, in-house, coding system, but for that I need to define it as appropriate ValueSet, bounded into appropriate Profile.


So this answer (and the question, really) applies to any property in a resource that has a type of Coding or CodeableConcept. In principle, any property of a resource that has a type can be filled by any one of those choices – a SNOMED CT code (or RxNorm, or LOINC, or …), a FHIR defined code, or a locally defined code. However for all these properties, we ‘bind’ them to a value set, and that value set makes a rule about what kind of codes can be used.

Element <– (binding) –> ValueSet

So if the property is bound to SNOMED CT, then you have to use a code from SNOMED CT. But note that if the type is CodeableConcept, which can have more than 1 coding, then this means that one of the codings has to come from SNOMED CT – for the others, you have can use anything at all that you like.

Further, the binding itself has an important property – the ‘strength‘ of the binding. This key property tells you how to interpret the binding:

required You have to use one of the specified codes
extensible You have to use one of the specified codes, unless there isn’t an appropriate one. Then you can use whatever you like
preferred This is the sort of codes you should use – and this value set really is a good idea to use
example This is the sort of codes you should use

So the last 2 binding strengths are not, well, binding: you can ignore them as you see fit. So what you can actually use in a resource property depends on the strength of the binding, and the value set it references. But, sadly, most of the really interesting properties in most resources have a binding strength of ‘example’ – precisely because they are most interesting, we have no way to get consensus on the right coding system (let alone the right set of concepts). A great example is Condition.code:

. code 1..1 CodeableConcept Identification of the condition, problem or diagnosis
Condition/Problem/Diagnosis Codes (Example)

An example binding to a large set of SNOMED CT codes….

Finally, some notes on your choices:

  • Standard clinical coding system: we always recommend that you use one of these. But these can be hard to use. We introduced the terminology service to make this easier, and this is a concept that’s just about in the goto-market phase
  • FHIR code systems are mostly defined for the fixed properties like status where you have to use one of the fixed codes we defined, but sometimes we define a code system to be used with Coding/CodeableConcept. We generally try pretty hard to not overlap with the standard terminologies, so it’s usually a choice of one or the other
  • When you use a customised in house coding system, you don’t actually have to define it using a value set, but doing so allows you to tell everyone else in a computable fashion what you are doing, so it’s a good idea, yes.



Question: How do profiles fit into the overall conformance picture


How are Conformance Resource and Implementation Guide (IG) resources are linked? I understand usage of both but how both will be linked to create Profiling.  Not clear about using both of them, what scenario or use case would be that?


Well the conformance resource includes server capability or client desire for server capability and also includes what all actual Resources are supported, and links to what profiles are (or should be) supported on the system. So the conformance statement ‘creates’ profiling by making it clear what profiles the system supports.

ImplementationGuide is a primarily a publishing thing – publishing a group of conformance statements and profiles, with their supporting value sets etc, in a single logical group, with a single identifier.  The implementation guide may – and commonly does, but not always – include one of more conformance statements as examples, or requirements. So it ‘creates’ profiling by allowing for publication of  group of conformance statements and profiles. So it’s primary function is to establish logical groups of profiles.

Most uses of Implementation Guide will be publishing national standards, or project agreements (projects such as argonaut) rather than server level publishing.




Question: where did the v2 messages and events go in FHIR?


I’m relatively new to the HL7 scene having implemented a few V2 messaging solutions (A08 , A19, ORU) and the V3/CDA work on PCEHR.  I am trying to get my head around FHIR.  So far I am stumped in how I would go about for example implementing the various trigger/messages I have done in V2.  Is there any guidance?  I cant find much.  Is that because the objective of FHIR is implementers are free to do it anyway they like?  If you could send me some links that would be a good starting point that would be great


Most implementers of FHIR use the RESTful interface. In this approach, there’s no messaging events: you just post the Patient, Encounter etc resources directly to the server. The resources contain the new state of the Patient/Encounter etc, and the server (or any system subscribed to the server) infers the events as needed.

A few implementers use the messaging approach. In this case, the architecture works like v2 messaging, with triggers, and events. However, because the resources are inherently richer than the equivalent v2 segments (e.g. see Patient.link), we didn’t need to define a whole set of A** messages, like in V3. Instead, there’s just “admin-notify” in the event list.

For XDS users (HIE or the PCEHR in Australia), see IHE’s Mobile Health Document Specification.


#FHIR in China

For the last few days, I’ve been in China for the China Health Information Network Conference 2016. I’d like to thank HL7 China and Professor Li (Chair, HL7 China) for inviting me – I really enjoyed the trip.


Simon Gong from Orion Health introducing me for the HL7 China technical session.

I was really keen to make this trip, because China is a really important potential stakeholder for FHIR. Not only is it a really large market, by many reports, Chinese medical practice can sometimes be quite different to western medicine, and I’ve worried that if China sits out the development stage of FHIR, and only gets involved late in the process, it might be too late for valid input to be heard.

I enjoyed my time in China immensely. I found a community struggling with the same things that challenge everyone. In fact, every time someone said to me, “What’s different about China, is that X is a problem”, I’d think to myself, yes, X is something that everyone struggles with to some degree or other. Interoperability is all about the people, and it’s the same in China just like anywhere else. But I think that what distinguishes China is the scale of the problem – China is vast, the healthcare system operates at a huge scale, modernization is happening so quickly, the economic factors that make it hard for vendors to collaborate are stronger, and the government’s ability to influence things (for good or bad) is stronger, etc.

Like many other countries, China is trying to figure out what to do about FHIR. Getting involved early in the process has it’s own costs, but gives you more influence over the final outcome, but sitting the process out avoids the cost of change and preserves your existing investment. I hope that my presence, my presentations, and my comments in discussion with Professor Li and others helped the Chinese community figure this out.

On other hand, several implementers described systems – including production systems – built using FHIR APIs – population surveillance, and clinical data repositories – just as real as anything built elsewhere. Some of these implementers I had already met, or even people who’ve contributed to FHIR (e.g. translations) – it was great to meet them in person. But others were new to me.

After my formal presentations, the HL7 China Technical Steering Committee (which is chaired by old friend JD Li), invited me to talk  with them about how to create an active FHIR community in China. They decided to plan a FHIR Connectathon for sometime in the period Oct – Nov, which we’re working on planning now. Also, by their request, I created a Chinese stream at chat.fhir.org. We also talked at length about translation plans, which is a significant issue in China. We didn’t make any solid plans in that regard, but the TSC will be working on that.

Hopefully we can build on the interest and commitment that already exists, and seed an active community that can catalyse wider uptake of FHIR in China.

Finally, I’d like to thank Sean Xie from Orion Health, who translated my presentations for me – Sean did a great job, and I really appreciated his excellent work.

Update: Chinese translation of this post from Linforest (thanks) (and with improved photos including Prof Li owning the floor while questioning me!).