The R in FHIR — Resources
Introduction
The R in HL7® FHIR® stands for Resources, but what exactly is a FHIR Resource?
Before getting into the formal definition of a FHIR Resource, let’s first appreciate some excellent design. In any complex system, we will almost always find an overriding design pattern or principle.
- The game of ice hockey is essentially a game of keep-away. Teams who keep the puck away from the other team the best, and shoot on the goal — win.
- Electronics are bound by relatively simple laws of physics, that, once understood and characterized into common building blocks (diodes, capacitors, resistors, etc.), can be assembled together to create some incredibly complex, and useful devices.
- In developing user interfaces for software, the event-driven programming pattern perfectly suits the task at hand — events happen, such as a mouse click, a key press, or a drag and drop operation; the user interface programmer’s task is to “catch” these events and do something useful with them — save a file, type a letter, or send an email.
In a similar way, Resources form the main design principle of FHIR and perfectly suit the design problem at hand. In this article, we cover the basics of FHIR Resources.
FHIR Resources — Defined
Resources represent key concepts found in the healthcare domain, making them the main building blocks of FHIR. Additionally, the FHIR specification defines a set of infrastructure Resources for handling FHIR Resources.
This may seem like circular logic, but that’s by design. To understand, let’s look at a few examples of FHIR Resources as defined by the FHIR specification.
- Patient — The most fundamental of all FHIR Resources. The FHIR specification defines a Patient as: “Demographics and other administrative information about an individual or animal receiving care or other health-related services.” (Animals are included in this definition of patients because it is possible to use FHIR in veterinary settings.)
- Medication: Tylenol PM, Percocet or Lorazepam: “This resource is primarily used for the identification and definition of a medication for the purposes of prescribing, dispensing, and administering a medication as well as for making statements about medication use.”
- Immunization: Influenza, or Hepatitis vaccine: “Describes the event of a patient being administered a vaccine or a record of an immunization as reported by a patient, a clinician or another party.”
- SearchParameter: “A search parameter that defines a named search item that can be used to search/filter on a resource.”
- CapabilityStatement: “A Capability Statement documents a set of capabilities (behaviors) of a FHIR Server for a particular version of FHIR that may be used as a statement of actual server functionality or a statement of required or desired server implementation.”
- StructureDefinition: “A definition of a FHIR structure. This resource is used to describe the underlying resources, data types defined in FHIR, and also for describing extensions and constraints on resources and data types.”
The first three Resources are quite common in healthcare — these are clinically oriented Resources. Patients are prescribed medications. Medications can be administered to a patient as an injection, for example. A patient may be immunized for Influenza.
The second set of three Resources are quite different — they are infrastructure Resources and are defined to help define and locate FHIR Resources. SearchParameters define the different ways that a FHIR Server may support searching for a patient — by last name for example. A CapabilityStatement Resource contains a list of all supported Resources available in a FHIR Server and the different interactions that may be available (read or write for example). StructureDefinitions are used to define… FHIR Resources. This self-definitional aspect of FHIR makes the FHIR specification quite powerful as a platform specification for healthcare, as we will see later.
What does a FHIR Resource Look Like?
Below is a Patient FHIR Resource expressed in JSON. XML is also supported by the FHIR specification. As you examine the structure, a FHIR Resource is a collection of elements that contain either primitive values, such as the “active”: true element, or a hierarchy of other elements, such as the “address” element which contains a collection of elements representing a postal address.
Let’s examine each section in detail.
Common Elements of Resources
All FHIR Resources have the following characteristics in common.
FHIR Resources have:
- A known identity where it can be located — its URL. Here is the Patient with id 12345: https://[FHIR server endpoint]/Patient/12345
- A FHIR Resource Type — identification of the type of Resource (e.g. Patient, or Medication)
- A FHIR server specific identifier (its FHIR id — 12345 in this example)
- A consistent set of metadata that provides context and workflow information about the Resource. For example, you will find a lastUpdated value in the metadata section that contains the date and time of the last change to the resource.
- A human-readable representation.
Above is a UML diagram of the Patient FHR Resource. We can see that the Patient inherits from a DomainResource, which in turn inherits from a Resource. These two foundational concepts contain the common elements for all FHIR Resources. We won’t discuss every detail of this diagram — larger topics like Profiles, Extensions, and others will be featured in future articles. Let’s walk through several of the key attributes:
Resource Identifier (id)
The id attribute in Resource is a logical id that never changes for the lifetime of the Resource. This logical id is either assigned by the FHIR server when creating a new Resource, or some FHIR servers support client-assigned ids, which is a convenient feature to use when duplicating FHIR data from one server to another.
In the example above, 12345 is the logical id for the Patient. Clients may request this resource by its location which is simply the base url, the resource type (Patient) and the logical id.
https://fhir.yourcompany.com/fhir/Patient/12345
It is important to note that the Resource Identifier is completely different than a business identifier (see the Patient “identifier” attribute mentioned below).
Metadata (meta)
The meta section in each FHIR Resource contains the following attributes which are helpful in resource management:
versionId
FHIR Resources may be versioned, should the FHIR server support this feature. For example, the initial version if a FHIR Resource may be 1, which can also be accessed at this location:
https://fhir.yourcompany.com/fhir/Patient/12345/_history/1
Should Patient/12345 be modified (for example, if a patient has a new, updated address), its name — or logical id will not change. The versionId will be updated to 2 when retrieved from this location:
https://fhir.yourcompany.com/fhir/Patient/12345
Additionally, the same resource can be retrieved from:
https://fhir.yourcompany.com/fhir/Patient/12345/_history/2
Note: The FHIR Specification does not require that the versionId be an auto-incrementing value beginning at 1. It may be a GUID like this:
https://fhir.yourcompany.com/fhir/Patient/12345/_history/038d12c2-ae9e-49b5-81d3-ba0af5ece9c3
lastUpdated
Simply the instant data type representing the last time this Resource has changed.
source
Answers the question: Where did this resource come from?
profile
FHIR Resources may conform to zero or more FHIR Profiles. Profiles are defined as StructureDefinitions.
security
Security labels such as the confidentiality setting of this Resource.
tag
Tags are simply a way to mark a Resource for future reference.
Human Readable Section (text : Narrative)
The FHIR Specification includes a text, or Narrative section for each Resource. This section is very helpful and valuable when using FHIR Resources as it contains a summary of the Resource that is intended to be displayed to a human.
Although FHIR Resources contain structured data elements, the Narrative section has enormous value to clinicians and patients alike in that it is the location where notes reside which has been generated by human brains — knowledge and many years of experience that are required to practice medicine may be found in the Narrative section.
The Narrative section is formatted in XHTML, which makes it very easy to display. An application can simply choose to render the XHTML as a convenient, and simple display option.
References Between Resources
Notice this attribute in Patient:
generalPractitioner 0..* Reference (Organization | Practitioner | PractitionerRole)
The generalPractitioner attribute is a Reference to another FHIR Resource. It may be a reference to an Organization, a Practitioner, or a PractitionerRole.
“reference”: “Practitioner/789”
is a relative URL which means it is relative to this server’s base FHIR URL.
Reference URLs may also be absolute — they may reference FHIR Resources on completely different FHIR servers or, (optionally) a specific version of a resource like this:
“reference” : “http://example.org/fhir/Observation/1x2/_history/2"
References may also refer to a Resource that is “contained” within the current FHIR Resource. For example, #p1 refers to the contained Practitioner resource within this Condition example:
{ “resourceType” : “Condition”, “contained”: [
{ “resourceType” : “Practitioner”, “id” : “p1”, “name” : [{ “family” : “Person”, “given” : [“Patricia”] }] }], “asserter” : { “reference” : “#p1” }
}
Summary
In this article, we discussed the basics of FHIR Resources, their structure, the common elements of all FHIR Resources the Narrative section, and how Resources may reference each other to form a web of related FHIR Resources.
As you can see, using FHIR Resources, it is relatively easy to decompose a clinical consultation into a set of FHIR Resources and associated references.
