Tag Archives: Forge

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:

"elementName[:sliceName].elementName[:sliceName]..."

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.

Advertisements

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”.

01-makeaprofile

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.

02-makeaprofile

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.

03-makeaprofile

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.

04-makeaprofile

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

05-makeaprofile

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”.

06-makeaprofile

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”.

07-makeaprofile

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.

08-makeaprofile

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

09-makeaprofile

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.

10-makeaprofile

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.

11-makeaprofile

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!

12-makeaprofile

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.

13-makeaprofile

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!

 

Finally

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.

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