Tag Archives: HL7

Element Identifiers in FHIR

In this article, we’ll take a closer look at element identifiers in FHIR, the relevant changes introduced by STU3 and the reasons that motivated that change.

FHIR has supported element identifiers since DSTU1. They are intended to specify unique identifiers for the elements within an individual resource. The official definition from the STU3 specification states: “The id property of the element is defined to allow implementers to build implementation functionality that makes use of internal references inside the resource. This specification does not use the internal id on the element in any way.

Element ids are particularly convenient to identify the individual ElementDefinitions inside of a StructureDefinition. In a basic StructureDefinition without slicing, each element definition has a unique path. However when a profile introduces slicing constraints, element paths are no longer unique, as the following example demonstrates:

Element name Slice name Element path
Patient Patient
identifier Patient.identifier
identifier ssn Patient.identifier
system Patient.identifier.system
identifier ehr Patient.identifier
system Patient.identifier.system

Clearly, the element path itself is not sufficient to uniquely identify individual element definitions, as we also require information about slice name(s). But if we would also include the slice name(s) in the expression, then the resulting value is no longer ambiguous and becomes a unique identifier:

Element name Slice name Element identifier
Patient Patient
identifier Patient.identifier
identifier ssn Patient.identifier:ssn
system Patient.identifier:ssn.system
identifier ehr Patient.identifier:ehr
system Patient.identifier:ehr.system

In order to support this, FHIR STU3 introduces some changes in the definition of element ids. The following table compares the specification of element ids in different FHIR versions:

FHIR version data type max length
DSTU 1 id 36 characters
DSTU 2 id 64 characters
STU 3 string 1MB

In STU3, the element identifier datatype has changed from id to string, effectively removing the maximum length constraint. Also, STU3 allows any string value that does not contain spaces, whereas in earlier versions, the set of valid characters was limited to A-Z | a-z| 0-9 | - | .

FHIR does not specify a mandatory format for element identifiers. In STU3, any unique non-empty string value without spaces is considered to be a valid identifier. However STU3 does introduce a preferred format for the identifiers of ElementDefinitions in a StructureDefinition resource:


Similar to the element path, the preferred identifier format specifies a number of path segments, separated by a dot “.” character. Each segment represents an individual element in the hierarchy and starts with the element name, optionally followed by a semicolon “:” character and the associated slice name (if not empty).

The preferred element identifier value only depends on the position of the element in the element tree. Different available representations of a specific ElementDefinition in both the differential and the snapshot component share the exact same identifier value. As the astute reader may have already noticed, this implies that element identifiers in the preferred format are actually not fully unique within the context of the containing StructureDefinition resource. Also, if we include multiple StructureDefinitions in a Bundle resource, then ElementDefinition identifiers of are not guaranteed to be unique within the context of the containing Bundle resource.

Note: When a FHIR resource is serialized to the XML representation, FHIR element identifiers are expressed as xml:id attributes. According to the W3C specification, “the [identifier] value is unique within the XML document”. So in fact, the FHIR specification violates the W3C XML specification… However in practical situations, this idiosyncrasy of FHIR shouldn’t pose an issue.

In general, software cannot assume that FHIR element identifiers follow the preferred format. The FHIR specification itself does not use the internal id on the element in any way (1). For ElementDefinitions contained in a StructureDefinition resource, the element name and the slice name remain to be the leading identifying attributes for processing logic to act on. This also implies that a sparse differential component should always include parent elements with a non-empty slice name, even if they are unconstrained. In theory, processing logic could reconstruct the parent element hierarchy by parsing the element identifiers in the differential component, provided that all identifiers are specified in the preferred format. However as the preferred identifier format is not required, generic logic cannot rely on this information.

Nonetheless, the standard open source Java and the .NET libraries for FHIR STU3 both provide implementations of a snapshot generator that can generate element ids in the preferred format. So within a clearly defined use context that guarantees standardized element identifiers to be present, e.g. because all snapshots are always (re-)generated by a standard FHIR library, it becomes possible to implement processing logic that acts on the standard identifiers.

Forge, the FHIR profile editor, introduced preliminary support for element identifiers as part of the initial STU3 release from May 2017. Initially, Forge allowed users to specify custom identifiers, however this feature has been deprecated since. As of release 16.4 for STU3, Forge will automatically generate element identifiers in the preferred format on all ElementDefinitions in both the differential and snapshot components. Users can not manually edit the generated identifiers.

1. ^ As Grahame points out in his comment, the FHIR standard actually does use element id’s as the target of content references. However these references do not rely on the format of the identifier.

SMART on FHIR and the Personal Health Record

The PHR is the holy grail of health IT. Whereas the EHR belongs to the doctor, the PHR – the Personal Health Record – belongs to the patient. The PHR combines your own data and data from your healthcare providers into one single overview, which you can share with physicians of your choice.

In May, during eHealth Week in Amsterdam, the Dutch patient federation NPCF (with support of the government) launched a project to create a PHR specification framework. This is a set of requirements any Dutch PHR will have to comply to. These include an infrastructural specification, judicial and financial arrangements, and the format of the data that is being shared.

Another important part of the specification is the way third party apps can access (read or write) data from a PHR. Based on one national open API, third party apps will integrate with any PHR without having to conform to a proprietary API each time they want to integrate with a new system.

One challenge here is how to give which app access to which part of the data? And what rights do they get? This is the same problem that EHR’s currently face. They want to open up their system, but only to trusted apps, and only those pieces of data that a particular app or person has the rights and needs for. In the US, major EHR vendors conform to the guidelines of SMART on FHIR for this purpose. Last Friday David Hay posted a blog about SMART on FHIR. In a nutshell: SMART on FHIR is a generic, standardized solution for apps running in an EHR. Any EHR.

To make it easy for developers to get started building apps based on the SMART standards, open source libraries are available that simplify and streamline the use of these standards in real world apps. Currently, libraries are available for HTML5/JavaScript, iOS and Python. This would be great for PHRs as well, since they face these exact same issues, and will now have a great way to safely open up their data to third party applications.

If you want to know more about SMART on FHIR, visit FHIR Developer Days 2016 in Amsterdam from 16-18 November. DevDays will host a specific SMART on FHIR track that focuses on app integration with the EHR according to the SMART on FHIR concept. Josh Mandel from Harvard Medical School / Boston Children’s Hospital (the inventor of SMART on FHIR) will explain the principles of SMART on FHIR and guide a hacking session. Two separate hacking sessions within this track will focus on app integration in the Epic and Cerner EHRs. These will be guided by interop experts from Epic and Cerner.

The DevDays Student Track is just a month away!

On the 19th of November, during the FHIR Developer Days (http://fhir.furore.com/Events/DevDays2015), students from 4 universities gather in Amsterdam to FHIR up the place. And I’m excited!

Around 20 students come here to the Furore Offices from:

  • Medical University of Vienna
  • University of Applied Sciences Upper Austria
  • Heilbronn University
  • University of Amsterdam (playing a home game)

We asked students to form teams of two or three persons and prepare for the DevDays by finding an API for a health-related device that they can easily access and write an adapter for. The adapter has to map data that they retrieve from the API into FHIR resources and then upload it to a server. We set up a Skype channel where the teams can discuss their solutions and ask each other (and some experts) questions when they are stuck.

Some projects the teams are working on:

  • Use a  FitBit REST API to get data from FitBit convert them into valid FHIR resources and post them on a FHIR Server and present the data in a chart for the customer.
  • Implement an Android based Bluetooth Low Energy Glucose meter to FHIR Bridge.

After the opening on Thursday morning the track will start with an introduction to FHIR by it’s founding father, Grahame Grieve. There will be of course some time for Q&A as well. After that, the student team start comparing their solutions, hopefully hack some new functionalities inspired by their colleagues, and have one big interoperability party by trying to combine multiple devices / data sources in their solutions.

At the end of the day, all teams will be asked to give a small demonstration, and there will of course be time for discussion as well.

As I mentioned before: “I’m excited!”

If you want to attend the student track of the DevDays, there is still room for a couple of teams. For more information please send me an email at m.smits@furore.com


FHIR profiles and implementation guides

The Furore FHIR team has recently been exploring the topic of authoring implementation guides for FHIR profiles. In this blog posting, I’d like to share some of our preliminary ideas with you. First let’s introduce a couple of key concepts.

So what is a FHIR profile? The HL7 FHIR standard defines a set of base resources, e.g. Patient and Observation. The standard base resources have very generic definitions. A FHIR profile allows you to author and publish a customized, more specific resource definition, by specifying a set of constraints and/or extensions on the base resource. Concrete FHIR resources like e.g. a Patient resource can express their conformance to a specific profile. This allows a FHIR server to programmatically validate a given resource against the associated profile definition.

Now assume we’ve authored a set of related profile definitions for our organization. We would like to publish some sort of manifest that lists all the relevant profiles and also some accompanying documentation. For this purpose, the FHIR standard introduces a Conformance Package. A conformance package typically contains:

  • A set of related resource profile definitions
  • A manifest listing all the available profile definitions (based on Composition resource)
  • An implementation guide describing the profiles

An implementation guide provides documentation about the package and the individual profiles targeting FHIR implementers and system integrators. You can find some examples on the official HL7 FHIR registry. As an implementation guide is an integral part of a conformance package, we would like to provide first-class tooling support for authoring implementation guides.

Let’s explore the requirements for an implementation guide:

  • Provide some general documentation about the conformance package
  • Provide detailed documentation for each of the individual resource profiles
  • Include documentation from external sources, e.g. if our package has external references to (third-party) profiles published elsewhere.
  • Include dynamically generated content, e.g. UML diagrams, hyperlinks to related documentation etc.
  • Support distributed content on different servers (conforming to the FHIR REST principles)
  • Define the content hierarchy
  • Provide documentation in multiple languages
  • Provide different sets of documentation targeting different audiences
  • Reuse common content in multiple implementation guides
  • Publish our implementation guide to multiple output channels (Web, mobile, PDF, …)
  • Clearly separate content from design/styling

The above requirements are closely related to Content Management Systems so we can reuse some architectural CMS concepts, e.g. the triangular relationship between content types, output channels and render templates.

CMS Concepts - MultichannelingIn order to ensure that our content is suitable for publication to any output channel, we should only provide limited styling options to documentation authors (paragraphs, headings, bulleted lists; cf. Markdown syntax).

Assuming documentation may be distributed over multiple servers (just like FHIR resources and profiles), how do we find the relevant documentation for a given conformance package?Implementation Guide - Resolving Documentation

  • Resolve the global documentation associated with the conformance package itself
  • Enumerate the profiling resources in the conformance package manifest
  • For each related profiling resource
    • Resolve and include the associated documentation (recursively)

The resolving process may be driven by global publication parameters such as  language and audience; e.g. find the available documentation for a given resource, for a specific language and a specific target audience.

In a forthcoming article we will explore this process into more detail and discuss some other aspects of the proposed architecture for authoring implementation guides.

The evolution of Profile to “conformance package”

First of all, let’s start with some introductions: My name is Marten Smits, I am Ewout’s colleague, and formerly an intern at Furore. I graduated last July at the University of Amsterdam, where I studied Medical Informatics. Since August, I have been part of the Furore FHIR team, where I have the privilege to work with FHIR full time. As I am typing this, I realize that I have been working with FHIR for over a year now, as it was one of the subjects of my graduation project as well. Wow, time really flies when you are having fun…. Anyway, I will join Ewout in writing blogs about FHIR on The Fhirplace!

San Antonio

In January, Ewout took me to my first HL7 WGM in San Antonio, where some of you may have met me. I have visited many different work groups, which were (almost always) very interesting, and where I learned a lot about the different aspects of HL7 standards. Of course our main interest at the WGM were the FHIR ballot comments. Issues, use cases, solutions, and (if necessary) changes were discussed by the work groups. Some issues were straight forward, and some were very complicated.

All major changes from DSTU-1 were discussed: newly introduced resources, the new JSON format, the introduction of Bundle (in favor of Atom) and many more. To my surprise, there wasn’t much discussion about the changes that were made on Profiles.

Profile: DSTU-1 vs DSTU-2 proposal

If you have taken a look at the Profile resource lately, you will immediately notice the changes that I am talking about.

Here is what the Profile resource looks like in DSTU-1:


The first time I saw that resource I was a little bit scared. This was definitely the most complicated resource in the FHIR specification at the time, and it took me a while to fully understand it. And one the first profiles I created had 13.000 lines of XML…

When I was preparing for the WGM in San Antonio, I took my first good look at the new Profile resource in the development version of FHIR. I first thought there was a bug in the website or that someone made a mistake, because what I saw was this:


I immediately turned around to Ewout (who has his desk right behind me) and I ask him: “Is this really the new profile? Where is all the rest?” He readily explained what happened to rest of the profile resource. I will give you a recap in this blog post!

Why is it so small?

The first thing you have to realize is that Profile is now something completely different than it was in DSTU-1. In DSTU-1 a Profile resource was something which described all the constraints on Resources, extensions and search parameters that you need in your use case.

The new Profile describes only the constraints of a single resource that you need in your use case. You could say that it is the equivalent of the Structure part of Profile in DSTU-1, including it’s reference to Element and ElementDefinition.

Where did the rest of the resource go?

As you probably have noticed, the Profile resource has gotten a lot smaller. Which immediately brings us to biggest change: Profile has been split up in multiple smaller resources:

  • Profile (formerly Structure in Profile)
  • ExtensionDefinition (formerly ExtensionDefn in Profile)
  • SearchParameter (formerly SearchParam in Profile)

The motive for splitting up the resource is actually really logical: This makes it easy to reuse the different parts of your Profile, which you could not easily do in DSTU-1. The lifetime of these separate resources are no longer bound together: you can refer to them separately, you can update them separately and you can refer to them like any other Resource. Finally, Profiles in DSTU1 turned out to be huge, so you were downloading a full profile just to get the definition of a single extension.

How do I combine the resources?

Once you have created new (or reused already defined) extensions and profiles. You might still want to combine them in some sort of package, to make sure that everyone who needs to use them knows that these are the rules that you use in your use-case. Just like you did in DSTU-1 with the large Profile resource.
I discussed that with Ewout, because I couldn’t find how to do this in the spec. He told me that FHIR is planning to use the existing Composition resource for this, where you can put in the metadata of your package, and use Compositions section structure to reference to different conformance resources. In practice this will look like this:


In this “Conformance Package” you have all the resources you need to describe your use case. As you can see these include far more different types of resources than were available in DSTU1. You can reference to the ValueSets that are typical for your use case, you can reference to your newly created Profiles (formerly Structure), and reference to Extensions and Conformance (describing compliance). Among The new DSTU2 conformance resources are OperationDefinition (describing additional operations on the REST interface), and NamingSystem (describing identifier or coding systems OIDs and urns in use in your context).

As you probably would have noticed by now I am very excited by this “evolution” of the profile resource. It makes life easier for the people who have to create profiles (or conformance packages), and also for the people who have to implement them. No more 13.000 lines of XML in one file, but smaller resources which can be more easily reused and altered. Now that I’ve almost finished this blog post I realize why there wasn’t any discussion about this major change in San Antonio: Profiling finally just feels right.

The only comment I have is the name. I suggest to name the new Profile resource “ContraintDefinition”, because it has a much smaller scope than the Profile resource in DSTU-1. Now, the name will just confuse people.

Questionnaires and the Connectathon

At the upcoming May HL7 Workgroup Meeting in Phoenix, we will organize the 6th FHIR Connectathon. Track 2 will focus on Questionnaires, so both client and server developers can test their skills at creating and supporting the Questionnaire resource. As well, David Hay has written additional information about it in his blog.

Basically, the Questionnaire can be used both as a medium to communicate filled-out Questionnaires, but it is conceivable -supported even- to exchange “empty” Questionnaires that don’t contain answers. In that case the Questionnaire contains just the questions, including their text, section headings etcetera. It matches the usual “paper” workflow where you send out an empty form, and get the same form back, but than filled with data. 

Of course, electronic forms can do much more than their paper counterparts, so you can stuff additional design information about a form into an empty form. Examples are graphic make-up, rules about hiding/showing questions depending on answers given and all kinds of validations. In DSTU1 we went for a general approach where Questionnaire’s basic “core” elements focused on supporting the exchange of answers (adding a few extra elements to include headers and prompt texts), but most other “form design” matter was to go into extensions.

One such extension is “answerFormat“. You can use it on a Question component to indicate the kind of answer you’re expecting (string, number, multiplce choice, etc.), and it mirrors the list of “types” people make up when they build eForms systems like SurveyMonkey or Excelsheets with minimal datasets. This data can be used for basic validation and UI building. No doubt you can go more fancy than this, but it should serve as a start.

Another extension is “mayRepeat”, which is only allowed on Groups of questions. The suggestion was that if you look at forms, you’ll often see repeating groups of questions, often layed in tabular form (with the question text in the column header). On the implementers Skype however, the question rose about how you would go about if you’d like a user to give multiple answers to the same question. Are these repeating questions with a single answer? Or one question with multiple answers? 

We concluded that, to stay aligned with the physical counterpart of a Questionnaire, it makes most sense to have multiple answers to a single question. You’re not repeating the question text, nor the header, instead you’re allowing multiple inputs to a question. Multiple answers, however, is not currently supported by Questionnaire’s Question component. To make this work, we are proposing to add an extension “additionalAnswer[x]” of type “decimal | integer | boolean | date | string | dateTime | instant to the “answer[x]” element. This extension works in the same manner as the current  “answer[x]” element which, mostly for technical reasons, was limited to 0..1. This extension may repeat, so you can give multiple answers:

<!-- stuff left out -->
     <system value="http://snomed.info/sct"/>
     <code value="228488005"/>
 <text value="What are your favorite colors?"/>
 <answerString value="red">
  <extension url="http://hl7.org/fhir/questionnaire-extensions#additionalAnswer">
     <valueString value="yellow" />
  <extension url="http://hl7.org/fhir/questionnaire-extensions#additionalAnswer">
     <valueString value="blue" />

For multiple-choices, you won’t need to use this construction, this is simply done by using the choice element, which may repeat and which represents the coded choices the user made (e.g. one or more codes from LOINC).

Because you’d probably want to limit the number of answers (“name your top three pastimes”), we’ll also add two extension “minCardinality” and “maxCardinality” to Question, both [0..1] of type Integer.

We’ll use these extensions during the connectathon and DSTU1, and any feedback will be fed into the community process leading up to DSTU2.

Authoring FHIR profiles

(and here’s part 2: ) https://vimeo.com/88235048

Granted, FHIR Profiles are some of the more complex parts of the HL7 FHIR standard, but also one of the most important ones to learn about if you want to adapt FHIR to your needs and usecases. With profiles you can:

  • Extend the FHIR Resources with your own data elements
  • Provide your own lists of codes to amend or replace the ones given in the standard
  • Limit cardinality on existing data elements
  • Define your own messages and documents

Find out more about Profiles in this presentation I gave at the last HL7 Workgroup Meeting in San Antonio. Thanks to Rene Spronk of Ringholm for taping and publishing this! You can find the slides to this presentation on Slideshare