Maturity Level: N/A | Standards Status:Informative |
Maturity Level: N/A | Standards Status:Informative |
POST [base]/ValueSet/$expand HTTP/1.1 Content-Type: application/fhir+xml <!-- This is an example of an operation request for a value set expansion where the value set is submitted on the fly --> <Parameters xmlns="http://hl7.org/fhir"> <parameter> <name value="filter"/> <valueString name="abdo"/> </parameter> <parameter> <name value="valueset"/> <resource> <ValueSet> <text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"><!-- Snipped for brevity --></div> </text> <identifier value="http://hl7.org/fhir/ValueSet/body-site"/> <name value="SNOMED CT Body Structures"/> <publisher value="FHIR Project team"/> <telecom> <system value="url"/> <value value="http://hl7.org/fhir"/> </telecom> <description value="This value set includes all the "Clinical finding" SNOMED CT codes (i.e. codes with an is-a relationship with 91723000: Anatomical structure)"/> <status value="draft"/> <compose> <include><!-- all the descendants of clinical finding, not include itself --> <system value="http://snomed.info/sct"/> <filter><!-- todo: work this over. what this means is any concepts where they have is-a with 91723000. how should this be done? --> <property value="concept"/> <op value="is-a"/> <value value="91723000"/> </filter> </include> </compose> </ValueSet> </resource> </parameter> </Parameters>
Maturity Level: Normative | Standards Status:Normative |
The RESTful API defines a set of common interactions (read, update, search, etc.) performed on a repository of typed resources. These interactions follow the RESTful paradigm of managing state by Create/Read/Update/Delete actions on a set of identified resources. While this approach solves many use cases, there is some functionality that can be met more efficiently using an RPC-like paradigm, where named operations are performed with inputs and outputs (Execute).
Operations are appropriately used where:
This specification describes a lightweight operation framework that seamlessly extends the RESTful API. The framework covers both how to execute such an operation (this page) and how to define an operation.
Operations have the following general properties:
Operations are executed using a URL derived from the FHIR endpoint, where the name of the operation is prefixed by a "dollar sign" ('$') character. For example:
POST http://fhir.someserver.org/fhir/Patient/1/$everything
When an operation has affectsState = false, and the parameters are all primitive data types with no extensions (as is the case with the example above), it may be invoked using GET as well. (Note: A HEAD request can also be used - see Support for HEAD).
Operations can be invoked on four types of FHIR endpoints:
The body of the invocation contains a special infrastructure resource called Parameters, which represents a collection of named parameters as <key,value> pairs, where the value may be any primitive or complex datatype or even a full Resource. It may also include strings formatted as search parameter types.
Upon completion, the operation returns another Parameters
resource, containing one or
more output parameters. This means that a FHIR operation can take a set of zero or more parameters in and return a set of zero or more
result parameters out. Both the body of the POST and the returned result are always a Resource.
Operations may be invoked using a GET
, with parameters as HTTP URL parameters, if:
If there is a single output parameter named 'return' then the response MAY be the resource that is the return value, with no Parameters resource. These kinds of usage are discussed further below.
If the response is a Bundle, the correct Bundle.type is 'collection', unless it has search semantics, such as matching resource counts, and page links (next etc).
Executing operations without any parameters is a special case. For an operation that doesn't cause any state change, the operation is invoked in a straight forward fashion:
GET [base]/Composition/example/$document
For operations that call state changes, they must be invoked by a POST. There is no parameters resource in this case because a parameters resource cannot be empty. So the operation is invoked with a POST with an empty body:
POST [base]/Claim/example/$submit Content-Length: 0
See the list of defined operations.
Implementations are able to define their own operations in addition to those defined here. Name clashes between operations defined by different implementers can be resolved by the use of the server's Capability Statement.
Also, the definition of these or additional run time operations does not prevent the use of other kinds of operations that are not dependent on and/or not integrated with the RESTful API, provided that their addressing scheme does not clash with the scheme defined here.
Each Operation is defined by:
For each parameter, the following information is needed:
Parameters may be nested into multi-part parameters. Each part has the same information as a parameter, except for use, which is taken from the parameter it is part of.
The resource Operation Definition is used to provide a computable definition of the Operation.
Implementations are able to extend an operation by defining new named parameters. Implementations can publish their own extended definitions using the Operation Definition resource, and this variant definition can use OperationDefinition.base to refer to the underlying definition.
Note that the FHIR specification will never define any parameter names starting with "x-".
Operations are typically executed synchronously: a client sends a request to a server that includes the operation's in parameters and the server replies with the operation's out parameters.
The URL for an operation end-point depends on its context:
An operation is generally invoked by performing an HTTP POST to the operation's end-point. The submitted content is the special Parameters format (the "in" parameters) - a list of named parameters. For an example, see the value set expansion request example. Note that when parameters have a search type, the search modifiers are available and are used on the parameter name in the Parameters resource (e.g. "code:in").
Note that the same arrangement as for the RESTful interface applies with respect to content types.
If all the parameters for the operation are primitive types and the operation
has affectsState
= false,
the operation may be invoked by performing an HTTP GET operation where all of the values of the parameters are appended
to the URL in the search portion of the URL (e.g. after the '?' character). Servers SHALL support this method of invocation.
E.g.
GET [base]/ValueSet/$expand?url=http://hl7.org/fhir/ValueSet/body-site&filter=abdo
When using the HTTP GET operation, if there is a repeating parameter for the extended operation the values for that parameter are repeated by repeating the named parameter. E.g. Observation $stats statistic parameter
GET [base]/Observation/$stats?subject=Patient/123&code=55284-4&system=http://loinc.org&duration=1&statistic=average&statistic=min&statistic=max&statistic=count
If, when invoking the operation, there is exactly one input parameter of type Resource (irrespective of whether other possible parameters are defined), that the operation can also be executed by a POST with that resource as the body of the request (and no parameters on the url).
Servers MAY choose to support submission of the parameters represented in multi-part/form-data format as well, which can be useful when testing an operation using HTML forms.
If an operation succeeds, an HTTP Status success code is returned. This will usually be a 2xx code, though it may also be a 303 See Other. Other kinds of 3xx codes should be understood to indicate that the operation did not proceed, and the client will need to re-issue the operation if it can perform the redirection (e.g. may get redirected to an authentication step). User agents should note that servers may issue redirects, etc. to authenticate the client in response to an operation request. An HTTP status code of 4xx or 5xx indicates an error, and an OperationOutcome SHOULD be returned with details.
In general, an operation response uses the same Parameters format whether there is only one or there are multiple named out parameters.
If there is only one out parameter, which is a Resource with the parameter name "return" then the parameter format is not used, and the response is simply the resource itself.
The result of an operation is subject to content negotiation like any other interaction. Specifically, if the returned resource is a Binary, the response SHALL behave in the same manner as if a 'read' operation had been performed on the resource. I.e. The content will be returned as either a FHIR resourse with base64-encoded content or as a raw binary, depending on the Accept header specified when invoking the operation (see Serving Binary Resources using the RESTful API ).
The resources that are returned by the operation may be
retained and made available in the resource repository
on the operation server. In that case, the server will
provide the identity of the resource in the returned resources. When
resources that are not persisted are returned in the response,
they will have no id
property.
Use the standard RESTful API Asynchronous pattern to execute operations asynchronously.
FHIR Infrastructure Work Group | Maturity Level: N/A | Standards Status: Informative |
The RESTful API defines a set of common interactions (read, update, search, etc.) performed on a repository of typed resources. For further information concerning how operations are defined and invoked, see Extended Operations on the RESTful API.
This is a full list of the operations defined by this specification:
Notes:
meta
element also operate on previous versions of a resource (/_history/). They are the only operations that can manipulate versions other than the "current" version.This specification defines a set of services, which are business level aggregations of Resources and Operations that provide a defined package of functionality that correspond to an identified business need.
Note that in addition to the services defined in this specification, many implementation guides define business level services.
This table lists the services currently defined:
Name | Description | Links |
Terminology Service | A service that lets healthcare applications make use of codes, code systems, and value sets without having to become experts in the fine details of the code system, value set and concept map resources, and the underlying code systems and terminological principles. The service provides the following functionality:
|
Capability statement module |
Conformance Service | A service that provides the underlying services needed to test whether resources conform to the rules defined by the FHIR specification and applicable implementation guides, and to help author implementation guides. The service provides the following functionality:
|
To be developed |
Knowledge Repository | A service that provides basic retrieval and maintenance functionality for clinical knowledge artifacts. The service provides the following functionality:
|
Capability statement module |
Measure Processor | A service that provides measure evaluation functionality. The service provides the following functionality:
|
Capability statement module |
Possible candidate Business Services for future versions:
Note that there is already past & current work on some of these in HL7 (though not necessarily FHIR specific).
Maturity Level: N/A | Standards Status:Informative |
At its core, FHIR contains two primary components:
In the healthcare domain, the set of “business objects” is not universally defined, but there is a notional and ongoing evolutionary, consensus-based process for standardizing on a core set of common business objects including things like “a patient”, “a procedure”, “an observation”, “an order”, etc. (see a list of defined resources). The FHIR specification provides a framework for defining these healthcare business objects (“resources”), for relating them together in a compositional manner, for implementing them in a computable form, and for sharing them across well-defined interfaces. The framework contains a verifiable and testable syntax, a set of rules and constraints, methods and interface signatures for “FHIR-aware” APIs, and specifications for the implementation of a server capable of requesting and delivering FHIR business objects.
From an operational perspective, HL7’s internal standards development and governance processes determine what constitutes a resource and which resources exist. In addition, the FHIR specification also provides a mechanism for contextualizing resources for specific needs within specific bounds (see Profiling Resources).
FHIR resources fit firmly within the information architecture domain and the FHIR APIs for data exchange address aspects of application architecture.
From a TOGAF perspective, FHIR addresses aspects of architecture views related to information model definition and data exchange, which are described in the Information Systems Architectures portion of the TOGAF Architecture Development Method. |
|
With regards to the Zachman Framework, FHIR fits within the What and the How dimensions of the Architect, Engineer and Technician Perspectives |
|
When considering the HL7 Services Aware Interoperability Framework (SAIF), FHIR resources and RESTful APIs represent the “Physical Models” and “Interface Implementations” within the Platform Specific Specifications layer of the Information Models and the Behavioral Models Viewpoints, respectively. |
|
FHIR’s primary purpose is to address interoperability with well-structured, expressive data models and simple, efficient data exchange mechanisms. In addition, FHIR aligns to the following architectural principles:
There are additional architecture principles related to consistency, granularity, referential integrity, and others that are not as well established or proven. See the section below on Outstanding Issues for details.
As discussed, FHIR’s principal components are resources and RESTful APIs. However, there is more to the FHIR specification including the components depicted below.
NOTE: The term “component” is used loosely to mean a part of something and does not intend to carry the specific meanings for this term provided by rigorous ontologies, modeling frameworks, or other architectural and organizational constructs. Diagrammatically, the components below are depicted below as UML classes. This is done purely to take advantage of the semantics afforded using this notation. FHIR is neither objected oriented in its modeling approach nor are the components that make up the FHIR specification UML classes or objects in the formal sense. Likewise, the UML packages shown below are notional and used for organizational purposes only.
As shown in the diagram below, it is convenient to think of the FHIR specification as having components that address the following:
Component definitions:
The following list provides general guidelines that apply when FHIR resources are defined. Most of these items are not enforced programmatically requiring human due diligence and governance to ensure adherence.
It is impractical to model the entirety of health data in a single information model. Every modeling initiative in healthcare from HL7 version 2 message specifications to FHIR resources decomposes the healthcare domain into smaller, more manageable sub-domains or information model snippets. With FHIR, each resource is essentially a snippet of the larger healthcare information domain.
When breaking down the healthcare information model into smaller chunks (or resources for FHIR), it is important to have a framework and set of guidelines to promote consistency and integrity within the resource structures and in the way resources reference each other. The framework shown below includes health information model sub-categories organized into layers based on their degree of commonness. The layers and categories are useful for identifying which parts of healthcare information are the most common and therefore need to be the most consistently defined and tightly governed. The categories at the top layers are the most common and contain the FHIR resources that support the largest number of common healthcare transactions.
Descriptions of the layers in the framework:
The complete set of FHIR resources organized against this framework is found on the Resources page.
The framework serves three primary purposes:
Purposes 2 and 3 set the foundation for future architectural rigor and resource governance to optimize consistency, integrity and predictability of new or refined resources in the future. The actual rules and patterns will be defined and refined in future FHIR releases. However, one general guideline to state now is that resources generally reference resources in the same layer or higher. In other words, a layer 4 resource will typically only reference resources in layers 4, 3, 2 or 1. There is nothing prohibiting a layer 4 resource from referencing a layer 5 resource, but this is not as common. Given this guideline, it is possible to identify the resources that are likely to be most common across use cases and therefore demand the highest degree of consistency and governance. Further, the framework helps identify the areas where creating new FHIR resources is the highest priority. It is generally a higher priority to create FHIR resources in the higher layers (layers 1, 2 and 3) than it is to create FHIR resources in the lower layers (layers 4 and 5) because the higher layer resources will provide the greatest value across the largest number of use cases and stakeholders. This is not to say that the business transactions needed for the higher layers are not important, it’s just that they are not as common across the whole healthcare space.
The 6th layer of the framework are not actually resources. Profiles and Graphs are extensions of resources or resource compositions that continue the progression through the FHIR Composition Framework. They provide additional contextualization required to satisfy certain use cases.
There are several benefits expected from aligning the creation of FHIR resources to this framework, including:
The framework is further elaborated in the FHIR Resource Considerations page.
Another useful tool for visualizing how FHIR resources are organized relative to each other can be found using the Resource Reference Visualization tool on clinFHIR.
A FHIR REST server is any software that implements the FHIR APIs and uses FHIR resources to exchange data. The diagram below describes the FHIR interface definitions. The methods are classified as:
Additional details on the FHIR APIs can be found at the FHIR RESTful API and the Operations Framework.
As mentioned, FHIR resources are optimized for stateless transactions with RESTful APIs. Although this is not the only way FHIR resources can be used, these types of transactions are the only ones with defined interfaces and behaviors in the FHIR specification.
FHIR transactions follow a simple request and response transaction pattern. The request and response can be for a single payload or can operate as batch. The payload or a request and response consist of a header and the content of interest. See diagram below for details.
(section to be filled out) (but see Security in the meantime).
Example Use Cases Using FHIR
For illustrative purposes, the following diagram depicts a simple use case of a patient accessing their personal health record (portal) enabled by an underlying electronic medical record (EMR) system. The EMR plays the role of the FHIR server in this example.
The pre-conditions for this use case are:
The basic flow of the use case is that the patient registers (if required), logs in, enters search criteria to identify a patient or patients of interest (the patient is most like themselves in this use case), retrieves clinical documents for the patient and retrieves clinical resources for the patient. The use cases utilize the GET methods on the iServeInstance interface and works with the following types of FHIR resources:
Although this example use case is very simple, more complex transactions using a combination of GETs, PUTs and DELETEs against resources and metadata can be envisioned. However, the exact details of these use cases including which methods are used, the orchestration of methods and the specific resources involved are outside the scope of the FHIR specification.
Maturity Level: N/A | Standards Status:Informative |
FHIR (Fast Healthcare Interoperability Resources) is designed to enable the exchange of healthcare-related information. This includes clinical data as well as healthcare-related administrative, public health and research data. It covers both human and veterinary medicine and is intended to be usable world-wide in a wide variety of contexts, including in-patient, ambulatory care, acute care, long-term care, community care, allied health, etc.
The FHIR specification is targeted to individuals and organizations developing software and architecting interoperable solutions that will be using FHIR. The FHIR specification does not attempt to define good or best clinical practices, nor does it provide guidance on user interfaces or workflows. Guidance in these areas may be useful, but it is outside of FHIR's scope.
Because of FHIR's focus on implementation, many aspects of the specification deal with the technical underpinnings of the exchange of clinical information between electronic systems. This section provides an introduction to what FHIR provides, and tries to highlight those portions of the specification that are likely to be of most interest to the clinical community while skipping over some of the technical minutiae of interoperability. However, clinical readers are welcome to explore some of the more technical areas if they find them of interest.
From a clinical perspective, the most important parts of the FHIR specification to understand are the Resources. Think of Resources as paper "forms" reflecting different types of clinical and administrative information that can be captured and shared. The FHIR specification defines a generic "form template" for each type of clinical information - so one for allergies, one for prescriptions, one for referrals, etc.
FHIR data consists of repositories containing completed "forms" (resource instances). The resource instances describe patient-related information (such as demographics, health conditions and procedures) as well as administrative information (such as practitioners, organizations and locations). Some resources are infrastructure components used to support the technical exchange of information by describing what systems are able to do, defining allowed sets of codes, etc. FHIR repositories might be electronic health record (EHR) systems, pharmacy systems, hospital information systems (HIS), etc. Some systems, such as clinical decision support engines, may expose FHIR interfaces even though they don't actually store any patient or administrative information themselves.
Each Resource defines a small amount of highly-focused data. A single resource doesn't say very much, but a collection of Resources taken together creates 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 paper forms (Resources) in FHIR are somewhat generic. They have to be usable in different countries and by different types of clinicians in different contexts (human care, veterinary care, public health, research, etc.). Recognizing that a one size fits all approach is not appropriate in the healthcare space, FHIR provides the ability to adjust the forms (Resources) to be able to handle the needs of different implementation spaces by defining "extensions" as well as enforcing constraints. For example, a "prescription" form might have extension elements added to support tracking of restricted medications while also constraining the codes that can be used to communicate types of drugs to a particular national standard. Forms are designed in such a way that these changes can be made without changing how systems pass forms around, enabling any system to consume completed forms even if they have additional elements added, whether or not those additional elements are used by the receiving system.
To keep the base forms that everyone uses from being overly complex, FHIR has a rule that, in most cases, a resource will only include data elements if there's an expectation that most implementations will use that particular data element. That doesn't mean the data must always exist. For example, most systems in the world are capable of tracking "deceased date" for a patient, even though that element will be blank for many patient records. On the other hand, not as many systems track hair color, so hair color would be omitted from the base form and those systems that need it (perhaps in a specialty clinical or research setting) can use a FHIR extension to capture it if needed.
To keep the number of resources reasonable, some of them are fairly broad. For example, the Observation resource is used for vital signs, lab results, psychological assessments and a variety of other things. To support setting rules for more narrow areas (e.g. "What should I send if I want to share a blood pressure?"), FHIR allows the creation of Profiles. There will be a great deal of clinical work involved in forming consensus around how different types of detailed clinical information should be captured and shared in particular settings. Tooling to support the creation of profiles directly by clinicians is part of the plan for FHIR, but is still in the very early stages.
FHIR is intended to support sharing data in a computable manner. I.e. The information shared should be usable for computer-mediated processes such as decision support, rules triggering, trend analysis, etc. However, not every system is the same and not all systems are able to recognize all discrete data. Also, there is still considerable value in data exchange in circumstances where not all or even none of that data is captured in a discrete manner. For this reason, FHIR resources support sharing not only discrete data for computation, but also a human-readable view so that the humans on each end of a healthcare information exchange can still get a full picture of what's going on.
Narrative is expected to exist for most resource instances, although it can be omitted in a few limited circumstances. In some cases, the narrative will be generated from discrete information. For example, the narrative for a patient might look like this:
Peter James Chalmers (OFFICIAL), Jim identifier: MRN = 12345 (USUAL) telecom: ph: (03) 5555 6473(WORK) gender: MALE birthDate: Dec 25, 1974 deceased: false address: 534 Erewhon St PleasantVille Vic 3999 (HOME) |
In other cases, the narrative might be free-form text commentary entered directly by a practitioner, such as referral letters, pathology reports, etc. Certain parts of the narrative content could also later be exposed as discrete data.
In addition to defining the "forms" for data exchange (Resources), FHIR also defines a set of interfaces by which systems actually share that information. There are four primary mechanisms or "paradigms" of exchange supported by FHIR: via a REST interface, by exchanging Documents, by sending and receiving Messages and by exposing and invoking Services.
REST is the simplest exchange mechanism. Continuing with the "form" metaphor, a RESTful server can be thought of as a room full of filing cabinets. Within the room is a cabinet for each "type" of form (or Resource) it supports. The cabinet contains folders where each folder has a unique number and represents one particular real-world thing: one Patient, one Encounter, one Medication, etc. Each folder (which represents a single Resource instance) contains multiple pieces of paper, with each piece of paper representing a specific "version" of that instance. Every time someone updates a record, a new piece of paper is added to the top of the file folder. To see the history of a resource, you simply have to flip through the pieces of paper in the folder.
Note that a typical medical record is generally a big "folder-of-folders" with many different types of 'forms' or 'reports' gathered together. This is convenient for someone who wants to review the whole record, but inconvenient for someone updating bits of it. There's always contention for access to it to update the right part. In the computer application the record will be decomposed to its smallest components for management purposes, and a computer will (or should) assemble the correct bits as required, by following references that exist from one piece of information to the next.
Now picture a clerk at the front door of that room. You can pass the clerk a requisition to have them do something with the information in those file cabinets. The "clerk" and the set of requisition forms on the clerk's counter make up the FHIR restful API. With that API, you can do the following:
EHRs and other systems may present a more sophisticated interface to their end users, but behind the scenes they're all making these same types of requests to the file clerk.
Documents are a familiar mechanism for sharing information in the healthcare space. They are useful whenever there's a desire to guide how a consumer of information will navigate it and there's a need to have a "frozen" view of information that can be reliably retrieved even years in the future. Examples of document-like things in healthcare include discharge summaries and lab reports.
In FHIR, there's a special resource called Composition that acts as the "cover page" for a document. It identifies the title, author date, relevant patient and the table of contents. A FHIR document can be thought of as a set of sheets (Resource instances) stacked together with a title page on top that's stapled together. That stapled collection can then be stored or passed around, conveying a complete set of information at once.
Much healthcare information exchange happens using a messaging paradigm. In messaging, a set of information is sent from one system to another, typically triggered by an event in the sender system. For example, a patient being admitted, a lab test being ordered, a drug being administered, the clock striking 12:00 or someone pressing a button. The message serves to notify the receiver that the event occurred as well as provide details about any existing data that was modified or new data that was created. Typically receiving a message means there's an expectation that the receiving system will "do something" in response.
A message might request that a lab order be fulfilled or notify a system that two patient records have been merged or that a patient has been transferred from one bed to another. A message is similar to a document in that it collects resources together, however for a message, the "cover page" is a MessageHeader that acts as a requisition. And rather than using a staple, the resources are joined together with a paper-clip and there's no expectation that the receiving system will store the contents of the message exactly as received, if at all.
Services can be thought of as a light-weight way of doing messaging. Rather than a full cover page, a small sticky note is attached to the front of a resource. And sometimes rather than sending a full piece of paper, the relevant pieces are cut out and sent as fragments. The response to a requisition is a similarly paper-clipped bundle of resource instances. Services are likely to be used for things like decision support. E.g. "Is there a problem with prescribing medication X for patient Y?" or "What's the recommended care plan for a patient with conditions A, B and C?"
A FHIR-based system's capabilities are defined by what the Resources can say and from a clinical perspective, these things define the clinical record:
This information can all be found in the resource definition pages. The resources most likely to be of interest can be found in the following modules:
Instructions on how to interpret the information found on the resource pages can be found here. The Logical table or the UML views are likely to be easiest to understand. Don't forget to look at the examples tab for an idea of what kind of information can be expressed. Seeing how elements are used to convey real data is often more useful than just looking at definitions. Also, look at the Profiles tab to see examples of how different resources can be constrained for use in particular contexts.
Clinician and other domain expertise and feedback is always welcome as we continue refining the FHIR specification. At the top of each resource page is a link to the home page for the work group responsible for that particular resource. If you have feedback on resource design, consider getting involved.
Maturity Level: N/A | Standards Status:Informative |
FHIR (Fast Healthcare Interoperability Resources) is designed to enable information exchange to support the provision of healthcare in a wide variety of settings. The specification builds on and adapts modern, widely used RESTful practices to enable the provision of integrated healthcare across a wide range of teams and organizations.
The intended scope of FHIR is broad, covering human and veterinary, clinical care, public health, clinical trials, administration and financial aspects. The standard is intended for global use and in a wide variety of architectures and scenarios.
FHIR is based on "Resources" which are the common building blocks for all exchanges. Resources are an instance-level representation of some kind of healthcare entity. All resources have the following features in common:
Resource instances are represented as either XML, JSON or RDF and there are currently different resource types defined in the FHIR specification.
This specification describes a set of resources - that is, a set of resource types that describe the set of resource instances that can actually be exchanged. The term 'Resource' is sometimes used without clarifying whether it specifically refers to types or instances - the context of use makes this clear.
This is an example of how a patient is represented as a FHIR object in JSON. An XML encoding is also defined in the specification.
{
"resourceType": "Patient",
"id" : "23434",
"meta" : {
"versionId" : "12",
"lastUpdated" : "2014-08-18T15:43:30Z"
}
"text": {
"status": "generated",
"div": "<!-- Snipped for Brevity -->"
},
"extension": [
{
"url": "http://example.org/consent#trials",
"valueCode": "renal"
}
],
"identifier": [
{
"use": "usual",
"label": "MRN",
"system": "http://www.goodhealth.org/identifiers/mrn",
"value": "123456"
}
],
"name": [
{
"family": [
"Levin"
],
"given": [
"Henry"
],
"suffix": [
"The 7th"
]
}
],
"gender": {
"text": "Male"
},
"birthDate": "1932-09-24",
"active": true
}
Each instance of a resource consists of:
Note that although this specification always shows the JSON properties in the order that they are defined, many JSON libraries order properties by other criteria.
For manipulation of resources, FHIR provides a REST API with a rich but simple set of interactions:
The FHIR specification describes other kinds of exchanges beyond this simple RESTful API, including exchange of groups of resources as Documents, as Messages, and by using various types of Services.
There is a wide variation between different geo-political jurisdictions and segments of the healthcare industry, and no central authority to impose common business practices. Because of this, the FHIR specification defines an extension framework and defines a framework for managing variability.
Another key aspect of the variability encountered in healthcare is that the same information may be represented differently and with different levels of detail, granularity and nesting by various parties across the system. For example, in some cases a blood pressure measurement may be just a simple observation, a vital sign measure, while in other cases can be a rich set of highly defined data that includes things like controlled vocabularies for posture, exercise, etc. The resource types defined in this specification focus on the general, common use cases. Richer and more specific content can be supported and standardized by defining "profiles" on the base resource types.
Versions, in the context of FHIR, means one of three different things:
FHIR Version
Usually, the FHIR version is fixed by the context - the CapabilityStatement that a client can use to find out about the server, but there are other ways of managing multiple FHIR versions.
Record Version
FHIR Servers do not have to support versioning, though they are strongly encouraged to do so. There are three different levels of versioning support for FHIR servers:
In addition, servers may require that version aware updates are used, to prevent over-writing changes, but this is not described on this page.
Business Version
Some resources - typically those that represent content that goes through a formal publishing cycle - carry
a version
element that explicitly states what version of the content the resource represents.
This is changed explicitly by a human, or by some automated process in accordance with applicable business
rules.
To create a resource, send an HTTP POST request to the resource type's respective end point.
POST https://example.com/path/{resourceType}
In the example below we see the creation of a Patient.
POST {some base path}/Patient HTTP/1.1
Authorization: Bearer 37CC0B0E-C15B-4578-9AC1-D83DCED2B2F9
Accept: application/fhir+json
Content-Type: application/fhir+json
Content-Length: 1198
{
"resourceType": "Patient",
...(properties)
}
Submit a new patient to the server, and ask it to store the patient with an id of its own choice.
Notes:
A response will contain an HTTP code 201 to indicate that the Resource has been created successfully. A location header indicates where the resource can be fetched in subsequent requests. The server may choose to return an OperationOutcome resource, but is not required to do so.
HTTP/1.1 201 Created
Content-Length: 161
Content-Type: application/fhir+json
Date: Mon, 18 Aug 2014 01:43:30 GMT
ETag: W/"1"
Location: http://example.com/Patient/347
{
"resourceType": "OperationOutcome",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">The operation was successful</div>"
}
}
Notes:
For a variety of reasons, servers may need to return an error. Clients should be alert to authentication related responses, but FHIR content related errors should be returned using an appropriate HTTP status code, with an OperationOutcome resource to provide additional information. Here is an example of a server rejecting a resource because of server defined business rules:
HTTP/1.1 422 Unprocessable Entity
Content-Length: 161
Content-Type: application/fhir+json
Date: Mon, 18 Aug 2014 01:43:30 GMT
{
"resourceType": "OperationOutcome",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">MRN conflict
- the MRN 123456 is already assigned to a different patient</div>"
},
}
Notes:
Reading a resource is done by sending HTTP GET requests to the desired Resource Type end-point.
GET https://example.com/path/{resourceType}/{id}
Here's an example.
GET /Patient/347?_format=xml HTTP/1.1
Host: example.com
Accept: application/fhir+xml
Cache-Control: no-cache
Notes:
The response to a GET contains the Resource.
HTTP/1.1 200 OK
Content-Length: 729
Content-Type: application/fhir+xml
Last-Modified: Sun, 17 Aug 2014 15:43:30 GMT
ETag: W/"1"
<?xml version="1.0" encoding="UTF-8"?>
<Patient xmlns="http://hl7.org/fhir">
<id value="347"/>
<meta>
<versionId value="1"/>
<lastUpdated value="2014-08-17T15:43:30Z"/>
</meta>
<!-- content as shown above for patient -->
</Patient>
Notes:
In addition to getting single known resources it's possible to find a collection of resources by searching the resource type end-point with a set of criteria describing the set of resources that should be retrieved, and their order. The general pattern is:
GET https://example.com/path/{resourceType}?criteria
The criteria is a set of HTTP parameters that specify which resources to return. The search operation
https://example.com/base/MedicationRequest?patient=347
returns all the prescriptions for the patient created above.
The response to a search request is a Bundle: a list of matching resources with some metadata:
HTTP/1.1 200 OK
Content-Length: 14523
Content-Type: application/fhir+xml
Last-Modified: Sun, 17 Aug 2014 15:49:30 GMT
{
"resourceType": "Bundle",
"type": "searchset",
"id" : "eceb4882-5c7e-4ca4-af62-995dfb8cef01"
"meta" : {
"lastUpdated" : "2014-08-19T15:49:30Z"
},
"total": "3",
"link": [
{
"relation" : "next",
"url" : "https://example.com/base/MedicationRequest?patient=347&searchId=ff15fd40-ff71-4b48-b366-09c706bed9d0&page=2"
}, {
"relation" : "self",
"url" : "https://example.com/base/MedicationRequest?patient=347"
}
],
"entry": [
{
"resource" : {
"resourceType": "MedicationRequest",
"id" : "3123",
"meta" : {
"versionId" : "1",
"lastUpdated" : "2014-08-16T05:31:17Z"
},
... content of resource ...
},
},
... 2 additional resources ....
]
}
Notes:
entry.resource.id
must be unique in the bundleThe client sends the server a new version of the resource to replace the existing version - it PUTs it to the location of the existing resource:
PUT https://example.com/path/{resourceType}/{id}
Note that there does not need to be a resource already existing at {id} - the server may elect to automatically create the resource at the specified address. Here is an example of updating a patient:
PUT /Patient/347 HTTP/1.1
Host: example.com
Content-Type: application/fhir+json
Content-Length: 1435
Accept: application/fhir+json
If-Match: 1
{
"resourceType": "Patient",
"id" : "347",
"meta" : {
"versionId" : "1",
"lastUpdated" : "2014-08-18T15:43:30Z"
},
...
}
Notes:
The response to an update request has metadata / status, and optionally an OperationOutcome:
HTTP/1.1 200 OK
Content-Length: 161
Content-Type: application/fhir+json
Date: Mon, 18 Aug 2014 01:43:30 GMT
ETag: W/"2"
Location: https://example.com/Patient/347/_history/2
{
"resourceType": "OperationOutcome",
"text": {
"status": "generated",
"div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">The operation was successful</div>"
}
}
Notes:
Here is an example that shows all the information found in all resources, fully populated:
{
"resourceType" : "X",
"id" : "12",
"meta" : {
"versionId" : "12",
"lastUpdated" : "2014-08-18T15:43:30Z",
"profile" : ["http://example-consortium.org/fhir/profile/patient"],
"security" : [{
"system" : "http://terminology.hl7.org/CodeSystem/v3-ActCode",
"code" : "EMP"
}],
"tag" : [{
"system" : "http://example.com/codes/workflow",
"code" : "needs-review"
}]
},
"implicitRules" : "http://example-consortium.org/fhir/ehr-plugins",
"language" : "X"
}
Implementers notes:
profile
, security
and tag
)The base properties of all resources are defined on the resource types Resource and DomainResource.
Want more information?
Maturity Level: N/A | Standards Status:Informative |
Welcome to the FHIR (Fast Healthcare Interoperability Resources) Specification, which is a standard for exchanging healthcare information electronically. This page provides an overview of the standard, and serves as a road map for first-time readers of the specification to help find your way around FHIR quickly.
Healthcare records are increasingly becoming digitized. As patients move around the healthcare ecosystem, their electronic health records must be available, discoverable, and understandable. Further, to support automated clinical decision support and other machine-based processing, the data must also be structured and standardized. (See Coming digital challenges in healthcare)
HL7 has been addressing these challenges by producing healthcare data exchange and information modeling standards for over 20 years. FHIR is a new specification based on emerging industry approaches, but informed by years of lessons around requirements, successes and challenges gained through defining and implementing HL7 v2, HL7 v3 and the RIM, and CDA. FHIR can be used as a stand-alone data exchange standard, but can and will also be used in partnership with existing widely used standards. (See Comparing FHIR to other HL7 standards)
FHIR aims to simplify implementation without sacrificing information integrity. It leverages existing logical and theoretical models to provide a consistent, easy to implement, and rigorous mechanism for exchanging data between healthcare applications. FHIR has built-in mechanisms for traceability to the HL7 RIM and other important content models. This ensures alignment to HL7's previously defined patterns and best practices without requiring the implementer to have intimate knowledge of the RIM or any HL7 v3 derivations. (See Comparing FHIR to other HL7 standards)
The basic building block in FHIR is a Resource. All exchangeable content is defined as a resource. Resources all share the following set of characteristics:
The philosophy behind FHIR is to build a base set of resources that, either by themselves or when combined, satisfy the majority of common use cases. FHIR resources aim to define the information contents and structure for the core information set that is shared by most implementations. There is a built-in extension mechanism to cover the remaining content as needed.
FHIR modeling uses a composition approach. In comparison, HL7 v3 modeling is based on "model by constraint" (see Comparing FHIR to other HL7 standards). With FHIR, specific use cases are usually implemented by combining resources together through the use of resource references. Although a single resource might be useful by itself for a given use case, it is more common that resources will be combined and tailored to meet use case specific requirements. Two special kinds of resources are used to describe how resources are defined and used:
Broadly, the FHIR specification is broken up into a set of modules:
Resources have a wide range of uses, from pure clinical content such as care plans and diagnostic reports to pure infrastructure such as Message Header and Capability Statements. They all share common technical characteristics (see below for a more formal definition), but they are used in totally different fashions. Note that you do not have to use REST to make use of resources.
The best place to start is to quickly read the Resources list to get a sense of what resources exist and then look at the Patient resource definition to see what resource definitions look like, and then read these background pages:
These header tabs found through-out the specification are important, and many readers miss them:
Resources and the data types that they use are presented in a concise easy to read XML-like format, but they also have detailed descriptions of their contents. In addition, most resources are mapped to several different formats, including HL7 v2, the HL7 v3 RIM, CDA, DICOM, and others. Also, all resources come with at least one example (sometimes many more) and, where appropriate, with profiles that describe their use in specific circumstances. Finally, some resources include notes that help implementers understand the design rationale underlying them.
While intended to be consumable by a variety of audiences, the FHIR specification is targeted to the implementation community - those who will actually write the software that uses the specification. To help meet the needs of the implementation community, the editors have strived to keep the specification concise to reduce the amount of reading that must be done before writing useful code. For this reason, information that is not essential to the implementation process, such as considered alternatives, points of contention, future plans, etc. have been excluded from this specification. As well, it is likely that from time-to-time, implementers will encounter situations where the specification is unclear or incomplete. Finally, there may be circumstances where the specification is broken or where a change could allow it to better meet implementer needs.
HL7 has therefore provided a number of mechanisms through which additional information about FHIR can be sought and maintained and through which support and requests for change can be made.
The FHIR project team also maintains a set of Confluence pages where development processes, methodology and design decisions are documented. Implementers and others can also contribute to Confluence to provide additional guidance and supplemental information not found in the specification. Note that Confluence content is not authoritative and is not relevant for determining conformance to the FHIR specification. As well, some Confluence content might not be up to date with the most recent version of the FHIR specification.
Pages defined include FHIR methodology, use of the FHIR design tools, etc. To explore the FHIR Confluence pages, you can start at the root page
Formal requests for change can be submitted here. (There's a link at the bottom of each page as well.) These will be reviewed by the appropriate work group and a decision made on their incorporation into the specification, including which release (if any) they will be part of.
In addition to the above mechanisms, HL7 provides a Stack Overflow tag, list servers and online chat system to provide various levels of implementer support and engagement. Instructions for accessing these other mechanisms (and instructions for how best to make use of them) can be found at the Support Links.