FHIR for Clinical Users

Note: this content will move into the FHIR specification itself when it is next balloted.

FHIR is a technical specification, which web–centric technical people understand easily. However the presentation is totally technology centric, and if you aren’t a technical person who understands web technologies, then it’s not obvious what FHIR is or how it works. But you don’t need to know the web side of the technology – the concepts underlying FHIR are really quite straight forward. This page explains the how systems interact with FHIR (which we call the Application Programming Interface – API) using a simple analogy, and if you get this, then you understand it enough to go off and review what really matters to clinicians – the clinical content of the resources.

Understanding the API

Think of FHIR as a filing cabinet. The cabinet has a series of drawers, seach with a label indicating the type of information inside. In each drawer there's series of numbered folders that represent discrete packages of information. Each folder contains a page, a form with a standard set of information written on it. A FHIR server grants access to the cabinet, and a client can ask it to perform a number of key operations:

• search: Search through the folders for ones that meet a set of search criteria
• read: Get a copy of one of a specific folders in the drawer
• create: Add a new folder to the appropriate drawer (with a new number)
• update: Alter the contents of a specific folder
• delete: Remove a folder from the cabinet (or more accurately, hide it)
• history: Get the history for one of the folders, or an entire drawer, or the entire system (ok, not such a normal cabinet- aren’t computers wonderful?)
• transaction: Give the server a bunch of folders all at once to update

In the FHIR ecosystem:

• Filing Cabinet: the FHIR Server
• Cabinet Drawer: a resource type, like Patient, Condition, or Observation
• Folder: a single instance of a resource type -- like the Patient 'John Smith' or the Condition 'John Smith's Asthma'

Building useful Clinical Systems out of Molecules

Each resource contains a small amount of highly-focused data. A single resource doesn’t say much, but a lot of very small resources together create a useful clinical record. Information systems map the actions that a user takes (look up patient records, make a note in their history, etc) to operations on the relevant resources.

The resources link to each other, and the links create a network (or web) of information that represent a health record (or at least, a useful part of it). Resources are linked to other resources based on the links that are defined, and clinical systems working with the record use these links to decide what resources they need for a task.

A FHIR-based system’s capabilities are defined by what the resources can say. From a clinical perspective, then, these things define the clinical record:

• the kinds of resources that are defined
• their data contents, rules about the data including what terminology codes
• how they link to each other
• how you can search for information

TODO: we’d like to have a schematic diagram that shows how the resources are related to each other – but it’s too big to be consumable. You can see the resources laid out by category at http://hl7.org/implement/standards/fhir/resourcelist.html

How the resources are described

To understand the resource contents, you have to learn to read the way the resources are presented. This is a very short tutorial as a starter.

Each resource is described by 6 different aspects:

• A scope statement, and rules and notes about its intended usage
• A diagrammatic summary of the contents
• An XML like statement of the contents
• A list of the terminology bindings (what elements use what codes)
• A list of rules about the data
• A list of criteria you can search by
• For example, let’s look at the Patient.

Scope Statement

This describes how the resource is expected to be used.

Diagrammatic Summary

This summary diagram shows all of the standard data elements contained in the Patient resource. Each data element has a name, a type that says what can be in it, min..max rules about its presence, and a terminology binding (see below).

Note: As a summary, this diagram doesn’t show the definitions of the data elements - you can see them by mousing over or clicking on an element's name (e.g. "gender"). Since the name of each field is not long enough to provide a complete description, it's very important to read the data element definitions. You can click on the datatype (e.g. HumanName) to see a technical definition of it, or you can refer to the table below in the Appendix.

Concise XML–like Representation

This is pretty the same information as the diagram above, except that it also contains a few extra words describing the element. This should be enough to understand the use of the element, though you can still access the full definitions by clicking on the element name. The green ‘data type’ can be clicked on to see the details. For example the patients name is a ‘HumanName’ and so contains the first name, last name and so on.

Note: The FHIR project team uses the diagrams for orientation and navigation, and the XML-like form when we’re working with the details.

Terminology Bindings

These specify what kinds of codes can be used for a particular field (e.g. “use SNOMED CT for your diagnosis code):

For each data element that has coded values, the bindings include an English-language definition, a reference to a value set that describes the actual list of codes, and a binding type. The possible binding types are:

• Fixed – only the codes that are specified in the reference can be used – nothing else is allowed (this means that everyone agrees completely – it doesn’t happen often)
• Incomplete – the codes in the reference should be used if they fit, or something else can be used
• Example – the specified codes are just an example to show what's expected

Rules about the data

Mostly these are fairly simple rules – e.g. in this case, if you list a contact, you must provide some details. Every rule has both an English description as well as a description that makes sense to computers

Rules about how to search for Resources

Finally, each resource type defines a set "Search Parameters," which are rules that govern a FHIR server's search operations. For example:

These are the ways that systems are expected to be able to search for the resources. These are directly clinically relevant – what do you want to be able to find one of these things by? If you’re looking for a patient, how would you search for the patient?

Other Features of Resources

• Links between resources are always defined in one direction, and systems use indexing capability to follow the links backward (so a DiagnosticReport links to a patient, and you can use an index to get all the DiagnosticReports for a patient)
• Versions – Actually, using the metaphor above, each folder contains a series of pages for each version, so you can look through old versions if you want to
• Extensions – all the resources can be extended to have new data elements in addition to the ones defined in FHIR. FHIR only defines the core/common elements that are widely used
• Narrative – all resources include a rich text representation of the data in the resource. If the system doesn’t understand the resource for some reason, it can always show the text to the clinician

Profiles

The resource definitions are very generic. They need to be useable in a variety of different systems – inpatient and outpatient, for different disciplines (psychology, oncology, social services) in different countries for different types of patients (pediatrics, geriatrics, veterinary), and in personal EHRs, clinical recording keeping systems, and secondary use systems. The resources are designed based on what most systems can handle now. Most of the data elements on the forms are optional because in at least some situations, the data won’t always be known or relevant.

This means that the standard data elements won’t always contain all of the data elements that are relevant in a particular circumstance. Nor will the form enforce the rules that may apply to a particular circumstance. E.g. A given hospital may have rules for the content of a referral for pediatric surgery at that hospital. It might require information such as primary care physician, parent names, child’s age and gender, etc. If any of those pieces of information are missing, it wouldn’t be considered a valid referral (for that type of referral at that hospital).

In FHIR, this is handled using a special type of resource called “Profile”. They make rules about the standard resources, saying things like:

• Which elements are required
• What terminology codes are used by a particular system
• What additional extensions are defined

Most of the real clinical knowledge about how particular things are/should be represented will be found in profiles. In the lab space, there would be profiles for base chemistry, Micro&Culture, Structured Histology reports etc. In the clinical space, profiles might be used to describe a standard set of observations and assessments for investigation of chest pain.

This is an area where FHIR still has considerable development to undergo yet.

Appendix: Data Types Summary

This appendix lists the data types, and summarises their use:

Simple Data Types : Low level IT centric kinds of data types

• string: A sequence of text characters
• integer: A simple number (no decimal places)
• decimal: Any real numerical value
• boolean: True or false
• base64Binary: IT name for a bunch of bytes a computer knows how to handle. For example: images, PDF documents, audio clips, etc.
• uri: A URL that a you can put in a browser, but also allows some other variations that a browser wouldn’t know
• instant: Date + time + timezone – when the system knows the exact time
• date: Date to whatever degree is known
• dateTime: Date/ Time to whatever degree is known
• code/oid/uuid/id: Particular kinds of strings with controlled values for identifying things

Complex Data Types: Common Patterns that occur throughout resources

• Attachment: A document, an image, etc – like an Email attachment
• Coding: A code, selected from some coding system (SNOMED CT, ICD-X, etc, or one made up locally)
• CodeableConcept: One or more codes and/or text. Mostly this is used instead of Coding because of the flexibility it allows
• Quantity: Some kind of numerical value with units. May also have a <, > on the value
• Range: Low – high quantities
• Ratio: Numerator : Denominator – used for titres and billing rates
• Period: Start date/time -> end date/time
• SampledData: A sequence of measurements from a device
• Identifier: Used to record identifiers associated with this thing
• HumanName: Surname, given names, name type, text summary
• Address: Postal address (country, state, zip, street address etc) + type and summary
• Contact: Telephone, email etc contacts
• Schedule: A set of future dates for something to occur (list of events, or a repeating time schedule)