Table of Contents
Introduction to FHIR
Fast Healthcare Interoperability Resources (FHIR) is the latest standard created by Health Level 7 to address the difficulties around data exchange between different health information systems.
What makes it different from its predecessors is that it adapts to new architectural paradigms and web development technologies. It has been met with great success, as evidenced by its adoption for their interoperability improvement strategies by:
- private companies.
- public organizations
New HL7 Europe FHIR Implementation Guides to support the European Health Data Space
Anatomy of a FHIR implementation guide
An FHIR Implementation guide is a set of documentation, FHIR resources and examples created to solve a specific use case within the healthcare domain.
PRACTICAL EXERCISE
Visit the HL7 FHIR Genomics Reporting Implementation Guide, which covers the standardization of the data exchange for a patient’s genetic information so that it can be accessed in a structured data format.
In the guide we find three fundamental elements:
- Documentation (in markdown)
- FHIR profiles (in JSON or XML) – these are special FHIR resources that are used to validate the agreed FHIR structure and terminology
- Examples of FHIR resources that have been adapted to the established FHIR profiles (again, in JSON or XML).
To learn more about HL7 FHIR Genomics Reporting Implementation Guide, read:
- Analysis done by the Electronic Medical Records and Genomics (eMerge) network , which maps fields from different genetics reports to the profiles in this guide.
- A scientific article about this work: Genomic considerations for FHIR®; eMERGE implementation lessons
See also: the full registry of FHIR interoperability guides
How FHIR implementation guides are generated
FHIR implementation guides are almost always presented in a standardized manner using templates, making easier for implementers to navigate the large volume of documentation created by different organizations and vendors.
To generate these implementation guides, open-source tool maintained by the FHIR community itself is used (Publisher) generates a ready-to-deploy web page from the three fundamental elements of the guides, we listed above.
Explore official documentation Publisher for generating FHIR interoperability guides.
Scalable FHIR implementation guides
An FHIR interoperability guide is a software project.
To ensure that all developments derived from a guide are robust and maintainable over time, the components must be managed using source code control.
This allows implementers to:
- Following the guide to track its evolution
- Adapt to new version changes
- Maintain a clear lineage between the guides and implementation
FHIR profiles in an implementation guide
The FHIR profile is the most important element of an implementation guide. It defines the syntactic and semantic structure of a dataset for the specific use case.
PRACTICAL EXERCISE
Check the Matchbox FHIR resource validation tutorial to understand how FHIR profiles are used.
Maintaining FHIR profiles over time
Maintaining FHIR profiles in JSON or XML has historically been a challenge for FHIR experts. Over time, FHIR profiles have been maintained in a variety of ways, including:
- Direct, manual editing of the the JSON or XML
- Editing in Excel spreadsheets that later generate the JSON or XML structures
- Using graphical interfaces that modify the JSON or XML directly
- Using FHIR Shorthand language. This is a programming language that generates JSON or XML structures through a JavaScript library called sushi
FHIR Shorthand language
Enables users to manage implementation guides like any other software project.
Specifically, FHIR Shorthand language:
- Reduces the complexity of managing FHIR profiles with JSON and XML
- Enables the introduction of CI/CD methodologies and source code control
- Is OS-neutral
See also: the full registry of FHIR interoperability guides using FSH
Get started with FHIR Shorthand language
The go-to resource for learning the FHIR Shorthand language is the official FSH School website.
You can either install FHIR Shorthand or use the FSH Online tool.
Installation is straightforward. But in our tutorial, we use the online tool.
The image shows the features you should learn, marked in yellow.
Create an FHIR profile
PRACTICAL EXERCISE
Go to FSH Online and define your Practitioner profile (MyPractitioner).
This profile must support your name, identifier, and qualification (to specify the specialty) fields. The identifier element can be sliced (see below) to support various types of identifier, such as passport or national ID. However, it must mandate just one ‘License Number’ from the fixed system.
http://example.com/myLicenseNumberIdentifier.
Now you can generate a compliant instance of your profile.
1️⃣ Click here to see the PROFILE SOLUTION
2️⃣ Click here to see the INSTANCE SOLUTION
3️⃣ Click here to see a WRONG INSTANCE, i.e. what happens when an instance does not follow the rules
EXTRA TIP: Go to the top left corner of the FSH Online, and click FSH Examples to get inspiration from the examples to complete the exercise.
In this exercise you have learned to:
- Define supported fields for your profile with respect to a reference FHIR resource
- Set a field as required
- Link a field to a specific text pattern
- Perform the technique called FHIR technique
FHIR SLICING is a mechanism that allows you to take a repeated element, such as a list of identifiers, and segment it into specific groups based on defined criteria. What is it for? Imagine you have the Patient.identifier element. By default, it is just a list of IDs. With slicing, you can say: “This list must contain one element that is a national ID, and may contain other elements that are passports.” You are defining different rules for different elements within the same list.
Make your FHIR profiles work with terminologies
PRACTICAL EXERCISE
Using FSHOnline, create an FHIR value set with the following SNOMED codes (system = http://snomed.info/sct):
- 394579002 “Cardiology”
- 394588006 “Pediatric oncology”
- 394593009 “Medical oncology”
Bind your new value set to the field qualification in the required mode.
Finally, generate a compliant instance of this profile.
Click here to see the PROFILE SOLUTION
Click here to see the INSTANCE SOLUTION
Click here to see a WRONG INSTANCE, i.e. what happens when an instance does not follow the rules
Do not panic!
Even though you are using a code that doesn’t exist in SNOMED CT and isn’t included in your value set, FHIR Online Tool doesn’t complain. Why? Because you need the FHIR validator to perform terminology validation rather than sushi.
You can see an example of a validation in Matchbox where a code is used that exists neither in SNOMED CT nor in the required value set.
In this exercise you have learned to:
- Create a value set
- Bind a value set to a field of a profile
- Differentiate between sushi validation and FHIR Validator validation
✏️ Customize your FHIR profile with extensions
PRACTICAL EXERCISE
Using FSHOnline, create a FHIR extension where I can place the years of experience of the Practitioner. Finally, generate a compliant Instance of this profile.
click here to see the PROFILE SOLUTION
click here to see the INSTANCE SOLUTION
Think through the creation of new profiles and extensions before your start. Someone might have had the same use case before you! See also: the full registry of FHIR extensions
In this exercise, you have learned to:
- Create an extension
- Link the extension to a specified FHIR profile
- Reuse extensions
✏️ Create a new FHIR profile from an inherited FHIR profile
PRACTICAL EXERCISE
Using FSHOnline, go to the Patient resource of the International Patient Summary (IPS) FHIR Implementation Guide, copy the JSON resource and transform it to .fsh.
Add your own profile (My Patient) based on the profile you inherited from IPS Patient, and ensure that it mandates language, gender, name and birthdate attributes.
1️⃣ Click here to see the PROFILE SOLUTION
2️⃣ Click here to see the INSTANCE SOLUTION
3️⃣ Click here to see what happens if you validate your instance, directly inherited from the International Patient Summary Implementation Guide, against an FHIR Validator.
You have just defined the attributes that you are going to populate for your use case. Your profile is compliant with the IPS implementation guide.
You are recycling FHIR profiles !
In this exercise, you have learned to:
- Create a profile from another FHIR profile
- Follow another FHIR profile at the same time that we add our own specifications.
✏️ Customize your FHIR profile with invariants
PRACTICAL EXERCISE
Go to the Patient resource in the International Patient Summary in .fsh, scroll down, and identify one invariant and how you can link that invariant to a profile. The image below shows an invariant.
This invariant tells you that if you populate the name field you have to populate the field family, given, or text.
Check this example that has just populated name.use in the FHIROnline tool, sushi validation is not complaining because it is compliant with FHIR, but…click here to validate the instance in the FHIR Validator.
FHIR INVARIANTS or constraints are formal rules that define business logic or clinical requirements that cannot be captured by simple data structures or cardinality alone. FHIRPath is the standard language for writing the logic for invariants.
Explore the official documentation of FHIRPath.
In this exercise, you have learned to:
- Recognize an invariant
- Link an invariant to a profile
- Validate an invariant
🤩 Extra points section: let’s build our implementation guide with FSH profiles
To get started:
- Install Publisher requirements
- Install sushi requirements
- Open your terminal:
sushi init
cd ExampleIG
./_updatePublisher.sh
./_genonce.sh
- Go to output folder and open index.html
- Take one of the .fsh files of the tutorial, create a new .fsh file and place it in the input/fsh folder.
- Run:
./_genonce.sh
- Open /output/index.html.
In this exercise, you have learned to:
🔥 Build an FHIR implementation guide with FHIR Shorthand (FSH) language.