Tag Archives: Profiles

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.

Make your first FHIR profile – within one hour! (Updated version Sep. 2016)

By Ardon Toonstra – Rob’s former blogpost of about a year ago may be a bit outdated but definitely not irrelevant. As FHIR is picking up speed more and more people are starting to model FHIR to their specific needs. For the beginners in FHIR modelling – better known as “profiling” –  this updated blogpost is the way to go.

As an example I will create a national ‘Dutch Patient’ profile. Even though Ewout Kramer is in the core team of FHIR, none of the specific concepts of our small country made it into the core spec of FHIR. In this blog, I will demonstrate how to make a customized profile.

Step 1 – Downloading and running Forge

Go to https://simplifier.net/  and click on Download Forge on the home page. Then create a free account on Simplifier.net, the global FHIR registry, before downloading Forge. This account may come in handy as this enables you to view and share your work in a click of button.

Click on ‘Goto Installer’ and ‘Install Forge’ for DSTU2 1.02. Accept the terms of both Microsoft (for the .Net runtime if you do not already have that) and Furore (for Forge). I can assure you both companies really exist and do no harm. After installing both components, Forge will automatically launch.

Step 2 – Creating and naming your own profile

In Forge, choose File – New Profile. The resource tab is now opened. This screen shows all available FHIR base resources. Select the “Patient” resource and click the “Select” button. In the Session Explorer on the left side you now see “MyPatient”.


If you click on MyPatient in the menu on the left you will open the Properties tab of MyPatient. Here you can amongst others: 1) enter a URL for your StructureDefinition (profile), 2) change the name of your StructureDefinition (profile) and 3) provide a description of your StructureDefinition.


Step 3 – Use slicing to add your own unique identifier

Next to the Properties tab you will find the Element Tree tab. This tab holds the element tree that contains all the elements of the base resource “Patient”. Forge offers multiple actions to modify a StructureDefinition. For example, you can change the information of the base elements, slice elements, or add extensions to elements.


Selecting an element in the tree will open the Element Properties on the right side of the screen. Examples of element properties are: the name, a short description, the cardinality and the datatype.

A patient usually has one (or more) identifiers. To specify multiple identifiers you can slice the element “identifier”. You do this by selecting the element you want to slice and click the Slice button. Once you sliced the element, you can add slices by clicking the “Add slice” button. For this example I added the Dutch Social Security Number, called burgerservicenummer. You can add more slices by selecting the element (identifier in this example) and clicking the “Add slice” button again.


Once you have created the slice burgerservicenummer, you can edit its properties in the Element Properties screen.


Step 4 – Use extensions to add a role to the contactperson of a patient

If the base resource does not contain all the elements you need, you can create an Extension for the element you need. Click on “New” and then on “New Extension” in the Solution explorer to create a new extension called “MyExtension”.


The extension also has a Properties and Element Tree tab where you can modify the information of the extension. In this example I want to add a “Role” to the contactperson of a patient. In the Properties tab of the extension I changed the name of the extension to “Role”.


To add the Role extension to the “contact” element in the PatientNL profile I first select the “contact” element. Secondly I click the “Extend” button.


This action adds the “MyExtension” element to “contact” element.


Selecting MyExtension will open the Element Properties window on the right side. In this window you can select the “Role” extension from a dropdown menu.


Under Name you can specify the name of the role of the contactperson of the patient.

Step 5 – Use referencing to make the contactperson part of an organization

Sometimes you want an element in a profile to reference another profile. For example, the contact of a patient can be part of an organization. If the profile Organization exists, you can reference to this profile by adding the canonical URL to the organization element in contact. To do this first select the organization element.


Then add the Profile URI to the reference data type in the Element Properties on the right site. If your customized profile Organization is opened in the Session Explorer Forge will automatically give that Profile URI as an option. Done!


Step 6 – Saving your profile

If your profile has a yellow star in the Session Explorer the profile has unsaved changes. To save your newly created profile you can select your profile in the Session Explorer and click the save icon. Ctrl + Shift + S allows you to save all profiles at the same time.


In the Save as dialog box, choose your name for the .xml file in which your Conformance Resource will be stored. You will also need to save Role, since it’s definition is a separate StructureDefinition resource. Both the PatientNL.xml and Role.xml file can be viewed with any xml browser, to see what Forge actually created.

As a default setting your profile is saved as a differential, which means it only saves the changes you made in comparison with the base resource. If you want to save your complete profile as an xml or json file, go to Options and check “Save snapshot component”.

Share your work with your team or the FHIR community at large!

Because Forge is integrated with Simplifier.net and you now have an account it is possible to directly render and share your work online via Simplifier.net. This blog shows you the couple of mouse clicks that are needed.

How to publish your profile – within one hour

By Ardon Toonstra – After completing your FHIR profiles, the next step will probably be to make them available to the world. Publishing your profiles will enable, for instance, app developers to build on your work. It may even be possible that your published profiles become the cornerstone of nationwide IT infrastructure for decades!

Assuming you have used Forge to author your profiles it will be very easy to publish your work thanks to the integration of Forge with Simplifier. Besides Simplifier, Forge is able to publish to any FHIR server with the click of a button. In this post, however, we will elaborate on publishing profiles to Simplifier. Simplifier is a registry for all FHIR resources. It facilitates you in using FHIR more efficient because of the ability to search and use previous work. Moreover, Simplifier can be used as platform to work on your profiles with multiple developers. I will come back on this shortly, but let me first demonstrate you how to publish your profile in two steps!

Forge: upload to Simplifier

After finishing your profile in Forge go to ‘File’ at the top menu and click ‘Publish to Simplifier.net’ (or press Ctrl + U instead). In the following screen you will be asked to give your Simplifier.net credentials. In case you do not have a Simplifier account, just register here. Create a project by going to your personal portal, the tab ‘your projects’ and click the button ‘create a new project’. Next, after you provided your credentials click Connect and wait a second until the Status says ‘Passed’. Now, you can select your project in which you want to publish your profile. Click the save button to finish the upload.

01_How to Publish

Forge integration with Simplifier

Simplifier: publish

Forge returns to its editor screen and your profile is now online at Simplifier. If your profile is truly ready for the world you can publish it at Simplifier. The next step will be to find your just uploaded profile in your project at Simplifier. Go to your personal portal on Simplifier and select the project under ‘Your Projects’. Click on your uploaded profile which can be found under the tab ‘Resources’. In your profile page, click the ‘Publish’ button in the top right beneath your username. That’s it, your profile is online and marked as published at Simplifier!



I promised you to continue about using Simplifier as a platform to work on your profiles with different users/developers. One of the reasons this works is the integration of Forge and Simplifier. Imagine that you would like to get feedback on your designed FHIR profiles. To arrange this, just upload the profiles to Simplifier and provide the desired users with the project name or link to your project. In this way you show them the rendered profiles in a coherent way and provide them the ability to download the profiles in XML or JSON format. Members of the same project, assuming they have the necessary user rights, can easily update the profiles by importing them into Forge and upload them again as described above. Thereby making FHIR even simpler!

If you have any questions, feel free to comment or contact us at simplifier@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.

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