#FHIR: Comments in JSON

We use XML comments extensively in FHIR for the examples in the specification:

  <Patient xmlns="http://hl7.org/fhir">
    <!-- this example patient shows how to use ... -->

Generally, comments are only useful in examples for the specification and implementation guides.

Unlike XML, JSON doesn’t have a comments syntax. Standing advice is to put the comment in some property, so that’s what we did:

    "resourceType" : "Patient",
    "fhir_comments" : "this example patient shows how to use ..."

But there’s problems with that approach – you’re parser has to parse them, and many people have trouble with the idea that you can truly ignore them. Then, if you’re using JSON schema, you have to allow for them. Also, if you’re round-tripping with XML, you lose the exact position of the comment. Finally, must human readers miss the comment anyway, since it’s in a property – and the human readers are the only point of having comments. (So many people use custom variations to include comments, but that’s not an option we have. The JSON community is discussing that, but it seems unlikely it will change, or if it changes, be widely adopted).

The cumulative effect of all this is that, as a consequence of a ballot comment (disclosure: from me) the HL7 ITS committee proposes to remove support for comments from the FHIR JSON format. Specifically, we propose to remove this paragraph:

There is no inherent support in JSON for a comment syntax. As a convention, content that would be comments in an XML representation is represented in a property with the name fhir_comments, which is an array of strings, which can appear on any JSON object. This is heavily used in example instances, e.g. in this specification, but not usually used in production systems (and production systems may choose to reject resources with comments in them)

We don’t know of anyone using this in practice, and for practical reasons, I removed comments from the actual JSON examples in the current version earlier this year, and we’ve had no comments about that. Never-the-less, the JSON format is labelled FMM 5 (see the specification definition), so we need to consult with the implementation community about this.

So we are calling for comment from implementers about this change. If you wish to comment on this change, please send an email to the FHIR email list before Octover 11th 2016. If you comment against this change, make sure you identify the production implementation that would be affected by the change, and how it would be affected.

Notes on #FHIR trademark usage

The FHIR trademark system is operational. There are 2 kinds of license to apply for:

You can use the name “FHIR” without applying for a trademark license in 2 circumstances.

Fair Use

You don’t need trademark permission to make use of the name “FHIR” to refer to the specification HL7 publishes, or the community that builds it. You can use “FHIR” as you like as long as you are referring to one of those things. That’s covered clearly under the “fair use” provisions of trademark law in most jurisdictions. HL7 asks that you mention that FHIR is a registered trademark, and provide attribution to HL7, but you don’t need to do those things under fair use law.

In practice, you can mostly differentiate between fair use and other kinds of use by inserting “HL7’s” into the sentence. For example, if you hold an event called “Learn about FHIR”, modifying the sentence doesn’t really change the meaning: “learn about HL7’s FHIR”. So that’s fair use. On the other hand, if adding “HL7’s” changes the meaning, it’s probably not fair use. For example, I maintain a server called the “FHIRServer” (and I don’t do that on behalf of HL7 as FHIR product director). Changing that to “HL7’s FHIRServer” is not correct – the FHIR Server is not ‘HL7’s server’. So that’s not fair use, and I need trademark permission (which I applied for).

We’re always happy to help members of the community determine what’s fair use – you can always ask me or Wayne Kubick (HL7 CTO) for assistance. (and we’ll be publishing an FAQ in the future on this)

Btw, using #FHIR on twitter is also definitely fair use.

HL7 Use

If you’re organising an event, or providing a resource, and the activity is organised by HL7 or an affiliate, and the activity is linked to a registered project in the HL7 database, or in an affiliate formal list, then you don’t need trademark permission – HL7 own the trademark for it’s own use.


HL7 has no choice but to enforce trademark protection, but we’re doing our best to make the trademark protection un-intrusive as possible. You don’t need any permission to talk about FHIR – even to be critical. But you need permission to use FHIR to describe something of your own. We’ll grant permission if you have a credible plan for alignment with the specification/community, and if you’re describing what you’re doing clearly, so that there’s no confusion about where the ultimate source of authority over the FHIR lies.


#FHIR Video Contest

We work hard to ensure that the FHIR specification is as easy to understand as possible. For example, we have several ‘getting started’ guides for different audiences. But never-the-less, getting orientated with the specification, and/or the FHIR connectathon process can still be a challenge. So today, HL7 is announcing a competition.

Contest entrants must post a video to Youtube that helps implementers ‘get started’ with the FHIR specification and/or the FHIR connectathons. Videos should be less than 5 minutes long, and be posted to Youtube by November the 1st.

Video entries will be judged by Ed Hammond (don’t know Ed? He’s “Mr HL7” is anyone is – see this award), and the winner will get free registration (or refund etc) for their next HL7 meeting.

Ed and I will be awarding some prizes for additional categories, including a ‘community preference’ award.

Call for comments: Logical references

Two tasks have been created from the current FHIR Ballot: 10354, and 10659. Both propose the same basic idea: to allow a reference to refer to an item by it’s logical identifier rather than a direct URL. This is a pretty significant change, so we’re calling for comments from the FHIR Implementer community.

The basic idea is pretty simple. A reference from one resource to another is a URL that identifies where the content of the resource can be found. For example, Observations nominate the patient that the observation is made on:

  <Observation xmlns="http://hl7.org/fhir">
      <reference value="http://acme.com/fhir/Patient/example"/>

This means that the patient resource can be accessed at the given URL. A reference can also be relative, like this:

  <Observation xmlns="http://hl7.org/fhir">
      <reference value="Patient/example"/>

This means that patient resource location is relative to the end-point at which the Observation was found. Both these approaches assume that the author of the resource knows exactly where the patient resource is found. In a purely RESTful environment, that’s a good safe assumption. But the FHIR community is encountering a number of situations where the address at which a resource is located is not know, even they key identifying information about the target is. In the case in point, this means that the application has a patient identifier, but it doesn’t know where the server for the patient is (or it doesn’t exist) and even if it does, the patient resource id the server uses it isn’t the same as the patient identifier, and there is no obvious conversion (in fact, it’s quite often that the patient identifier is not sufficiently reliable to use in the URL – they change…).

So the proposal is that FHIR should change so that this is valid:

  <Observation xmlns="http://hl7.org/fhir">
        <system value="http://hl7.org/fhir/sid/us-ssn"/>
        <value value="5551234567"/>

This is a reference to a patient by their identifier. It’s the responsibility of the reader of the resource to decide how to resolve this reference to a resource (or some other kind of resource) – if they can. Or to decide what to do about it if there’s multiple candidate matches – which is also possible.

This is a fairly significant change. There’s already resources where this pattern is baked in by using a data type choice – see, for example, ExplanationOfBenefit:


Generalising this pattern so it applies anywhere there’s a reference – without having to be explicit in the design as above – is both good and bad, depending on who you are. Generally, it allows a resource writer to move work to the resource reader, but it also allows a resource writer to write resources it otherwise couldn’t?

We’re calling for comments on this issue from implementers, to help us decide. Please comment on the second task (10659)

#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).