Most FHIR projects use only a small sub-set of FHIR resources. 10-20 is common. Within those resources, different projects make use of different elements and attributes.
What this means for developers is that they often find themselves using only those aspects of FHIR that fit neatly into their current project. Entire sets of functionality can be unknown to them.
Here are 6 features of FHIR that I’ve found many developers are surprised by when they encounter them.
1. FHIR Ancestors
There is a hierarchy to FHIR resources. Most resources inherit from DomainResource and ALL resources inherit from Resource.
- DomainResource contains the text, contained, extension and modifierExtension elements.
- Resource contains the id and meta elements.
- The Meta element is where you find common attributes such as versionId, source, profile and tags.
Where developers often get lost is in trying to locate the above elements as they are not immediately visible on a resource’s documentation page.
The three resources that inherit directly from resource — bypassing DomainResource — are Bundle, Parameter and Binary. You cannot add a root extension to any of them.
More about Domain Resource.
More about Resource.
2. Security Labels
Security Labels form part of a resource’s Meta element and “Connect resources to an overall security policy.”
What makes them of real significance to developers is that they cannot be ignored. If data flows into your FHIR server with a particular security label, you have to support it and take appropriate action.
They tend to fall into three categories:
1. Purpose of Use
What is the data being used for? “Clinical trial” is an example. You don’t want to use this data for non trial purposes.
2. Data Sensitivity
Confidentiality levels such as “very restricted.” These resources should be treated differently in user interfaces and when access controls are implemented.
3. Control of Flow
How must you treat the data after you receive it. Examples are “delete after use” and “test data.” If you ignore this label you could find yourself in hot water when you fail to delete data as expected or treat test data as if it were live data.
The key takeaway here is that not being aware of security labels and how to handle them is dangerous. In some jurisdictions there are severe penalties for not correctly actioning them.
3. Custom SearchParameters
We’re all familiar with extensions. But extensions are only one way to extend FHIR to meet a project’s needs. Almost all FHIR servers support the creation of custom SearchParameters.
This is where you define a new SearchParameter that references elements in one or more resources. It allows you to perform searches against their values.
SearchParamaters can be created for all elements in all resources, and for any extensions you may have created.
- You create a SearchParameter resource with a simple or complex fhirPath expression
- You add the resource to your FHIR server
- You trigger the activation of the SearchParamater (different process for each server provider)
Developers who are unaware of the ability to create custom SearchParameters often find themselves writing code they don’t need to write and paginating through resources in an effort to duplicate the work of a SearchParameter.
How to create a SearchParameter.
4. Contained Resources
A resources within a resource.
Contained resources are not complete resources. They cannot have extensions. They cannot contain other resources — no nesting. They cannot be referenced outside their parent resource.
They are often used when data flows into your FHIR server from an external source. That data may contain records that do not belong to your organization but still form part of the incoming data flow.
Let’s say you’re pulling in a list of Procedures that occurred in a sister hospital. These procedures were performed by doctors who are not in your system. The transaction Bundle that you receive might contain a Procedure and Patient resource, but not a Practitioner resource.
The Practitioner resource might exist as a contained resource inside the Procedure and only list the doctors name, with no identifier or other information about the doctor.
Many developers who have never worked with contained resources are surprised when they encounter them in incoming data. Others may have read up on them and try to use them in ways they are not meant to be used.
More about contained resources.
5. Resource References
One of the core building blocks of FHIR that connects resources to each other.
Developers use resource references all the time and generally have a solid understanding of how they work. But even within such a commonly used data type there can be surprises.
This is what they usually look like:
- Relative URL: Patient/7480947
- Absolute URL: http://hapi.fhir.org/baseR4/Procedure/7481046
- Logical URI: urn:uuid:a9ba7c98-9ab3-4a25-b894-73dda76eed3d
But… did you know that a resource reference does not have to reference another FHIR resource via its ID as shown above?
All elements of the Reference element are optional, and one of those elements is the less commonly used Identifier. This is a logical reference (usually a system / value pair), and may be used when the literal reference is not known.
What if we don’t even have an identifier? What if there is no entity that we can reference but that the entity exists in name only?
The Reference.display value may be populated with a string value identifying the entity. This is not good practice, but you might encounter it in real world data.
I’ve typically seen this structure used in resources such as AuditEvent, where the mandatory source.observer element is populated by a string value such as “system.”
I’ve also seen this very structure break code when developers were expecting more complete resource data.
More about resource references.
6. The _elements parameter
Not all FHIR servers support the _elements parameter, but when they do your developers should be using it where appropriate.
It allows you to specify in a query string precisely which elements of a resource you want to see in the returning request body.
This is especially useful when you’re consuming resources that might contain binary data such as PDF files or photos. Without specifying which elements you want, you’ll receive everything.
Paginating through 20 Patients — each with an attached photo — could easily lead to request sizes of 50 or 100 mbs. A very real problem if you’re iterating through thousands of patients or displaying data in real time on a screen.
More about the _elements parameter.
---