Maturity Level: N/A | Standards Status:Informative |
FHIR is a framework standard that defines a common way to solve healthcare problems and provides a set of resources that can be used in many different ways. This page describes how certain common usage scenarios are implemented using the capabilities that FHIR defines. The provided scenarios are examples of usage and are not in any way exhaustive. FHIR can and will be used in a wide variety of circumstances.
In addition, to the information on this page, see also Resource Guide.
Note: Further significant development in the area of consumer centered data exchange is expected for the next release of this specification (R5).
In the PHR scenario, an Electronic Medical Record system (EMR, though many other names and acronyms are also used) provides a RESTful API that allows patients to access their own medical record via a common web portal or mobile application, usually provided by a third party. In this scenario, the PHR provider:
The EMR exposes a FHIR server that supports the search and read operations on the following resources:
Here is the Capabilities Statement for this scenario: XML or JSON.
The EMR may also choose to provide additional functionality, such as shared access to patient records by relatives/carers, to allow the patient to upload their own documents, medication statements, observations (e.g. from patient monitoring devices) and/or to allow the patient to make appointments. This additional functionality will involve additional API capabilities to be implemented and exposed. The EMR server may also choose to expose the search, read and history operation on the AuditEvent resource for the patient-specific records to allow patient review of record access. Note that all usage of the RESTful API should be logged in an AuditEvent resource.
One common way to integrate healthcare information from a variety of sources is to build a repository of documents around a patient record. Building a repository of documents allows for less stringent alignment around policy, procedures and record-keeping/informatics standards.
The most widely adopted framework for sharing documents within institutions, regions, states or countries is IHE Cross-Enterprise Document Sharing (XDS). XDS allows for a federated system of repositories with a registry to provide coordinated access to the documents.
FHIR provides equivalent functionality to XDS that can be used to implement XDS behind the existing XDS.b interface, to provide a simpler mobile-friendly interface to an existing XDS ecosystem, or to link document sharing into other functionality provided through a FHIR interface.
The following FHIR Resources are involved in the XDS functionality:
At present, IHE is working with the FHIR project team to use FHIR for Mobile Health Documents (MHD).
One common use of healthcare information systems is to integrate some form of decision support software into clinical systems. Common uses of clinical decision support are:
Note that in addition to clinical decision support, there are also infrastructural uses, such as managing access control.
The various forms of decision support each involve different interaction patterns, so there is no single decision support implementation in the FHIR specification. Generally, the patterns fall into several classes:
Any decision support may fall into multiple categories at once, depending on the perspective of a particular system.
When a query is initiated in order to get a decision made, the following considerations apply:
Request
Response
It follows from this then, that decisions that may be requested need at least a response resource defined, and possibly a request resource. This table summarizes known decisions for which resources have been defined.
Decision | Resources | Invocation |
What immunizations should this patient have? | Response: ImmunizationRecommendation | The exact way to invoke this decision is not yet defined |
Implementers are allowed to use existing resources for decisions not documented here, but there is no guarantee that they will be suitable. Improving decision support will be a focus for ongoing development during the Trial Use period.
Maturity Level: N/A | Standards Status:Informative |
This page provides an overview of how the FHIR specification supports validation of resources.
Validating a resource means, checking that the following aspects of the resource are valid:
There are multiple ways to validate resources. This table summarizes the options described in this specification, and which of the aspects above they can validate:
Method | XML | JSON | RDF | Structure | Cardinality | Values | Bindings | Invariants | Profiles | Questionnaires | Business Rules |
XML Schema | ![]() |
![]() |
![]() |
![]() |
|||||||
XML Schema + Schematron | ![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
|||||
JSON Schema | ![]() |
![]() |
![]() |
![]() |
![]() |
||||||
ShEx | ![]() |
![]() |
![]() |
![]() |
![]() |
||||||
Validator | ![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
|
Validation Operation4 | ![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Notes:
Note that all these validation methods are incomplete; they can only validate the computable aspects of conformance. There are always additional rules made in narrative that they are not able to check (e.g. a rule such as "All the clinically important content in the data SHALL be in the narrative", which might be made in an implementation guide, but could never be checked by a conformance tool).
In case of disagreement between these conformance methods, note that:
Also, note that static testing of resource content is not enough to prove conformance to the specification. For further information, see FHIR Conformance Testing.
Servers and clients may be configured to validate content when it is received (e.g. some of the public testing services validate resources on create/update). This can be done both during development and in production use of applications in healthcare processes. While use during the development cycle is highly recommended, use during production might not always be a good idea:
On the other hand, validation during production use may be very important:
Generally, following Postel's law is recommended:
An implementation should be conservative in its sending behavior, and liberal in its receiving behavior.
Applications should consider carefully how much validation beyond the security related issues to perform at run-time, and how errors will be handled.
The XML schema can be used to validate XML representations of the resources. When validating a resource, you can nominate one of the following schema:
In addition, the validation schema includes schematron that can be initiated with transform "iso_svrl_for_xslt2.xsl" included in the XML Tools download. Note that XSLT2 is required to run the schematrons.
When running the schematron, use the file "fhir-invariants.sch". This includes all the schematrons. The individual schematron files for each resource are provided to allow implementers to build their own smaller combined file that covers the relevant resource types for them.
The JSON schema can be used with JSON schema validation software. Links:
The FHIR Validator is a Java jar that is provided as part of the specification, and that is used during the publication process to validate all the published examples. To execute the FHIR validator, follow the following steps:
Here is an example windows batch file that demonstrates the process (using the common utilities wget and 7z):
@ECHO OFF ECHO get the validator and unzip it wget http://build.fhir.org/validator.zip 7z.exe x validator.zip ECHO 1. First example shows how to validate against the base spec: ECHO a. get an example to validate wgetpatient-example.xml -O pat-ex.xml ECHO b. validate it against FHIR R3 java -jar org.hl7.fhir.validator.jar pat-ex.xml -version 3.0 ECHO 2. Second example shows how to validate against a profile in the spec: ECHO a. get an example to validate wgetobservation-example-heart-rate.xml -O obs-ex.xml ECHO b. validate it java -jar org.hl7.fhir.validator.jar obs-ex.xml -version -profile http://hl7.org/fhir/StructureDefinition/heartrate ECHO 3. Third example shows how to validate against a profile in an implementation guide: ECHO a. get an example to validate wgetobservation-example-heart-rate.xml -O obs-ex.xml ECHO b. validate it. note that you have to tell the validator where to get the implementation guide information java -jar org.hl7.fhir.validator.jar obs-ex.xml -version 3.0 -ig http://hl7.org/fhir/us/core -profile http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient ECHO Press Any Key to Close pause
Note that it is not necessary to download the resource first; the http address can be supplied directly:
java -jar org.hl7.fhir.validator.jar/patient-example.html -profile http://hl7.org/fhir/StructureDefinition/Patient
The validator requires an underlying terminology server. By default, this is http://fhir3.healthintersections.com.au. For further details of the parameters supported by the validator, see Using the FHIR Validator
The operation validate can be used to check whether a resource conforms to a profile. The simplest way to execute this operation is to post the resource to a server:
POST [base]/Observation/$validate?profile=http://hl7.org/fhir/StructureDefinition/heartrate [other HTTP headers] <Observation>... resource to check as the body
The server will return an OperationOutcome resource listing issues found in the resource.
There are several things to consider when using this operation:
Some servers expose the $validate functionality through a web page. For known public implementations, see the FHIR Confluence page
Maturity Level: N/A | Standards Status:Informative |
This FHIR specification is one in a series of publications of the FHIR specification. There have been previous releases, and there will be subsequent releases. Each release (or "version") introduces new features, and changes from the previous releases.
Implementers should be familiar with the kind of changes that can be made, and the change processes that apply - see the FHIR Version Management Policy for further information
Ongoing change to the specification means that implementers must be able to determine which version is in use in their context, and implement accordingly.
There are 3 ways to determine the version of FHIR in use:
Whenever resources are exchanged, the applicable FHIR version applies to the entire interaction, not just the resources. The semantics of the mime types, the RESTful URLs, the search parameters, and the overall interaction are bound to a particular FHIR version. The resource versions must be consistent with the overall interaction. It’s not possible for client/server (or, for messaging, sender/receiver) to have a coherent conversation without first agreeing on the version. The version of the interaction is specified in the CapabilityStatement resource. The sequence works this way:
Clients are advised to check the server’s capability statement before first using the server, but how often is at the discretion of the implementer, and this varies wildly. Some implementers only check the statement during the development cycle, while others check on the first connection for each process. Which is appropriate depends on a variety of circumstances, but implementers should note that the CapabilityStatement can change over time - even changing FHIR versions as the system is subject to ongoing development.
Note that there are related places where the FHIR version in use can also be stated, and these may be consulted at different points in the development cycle in place (or as well as) CapabilityStatement.fhirVersion:
The most common strategy for handling change between versions of FHIR is to use different end-points for different versions. e.g. http://acme.com/fhir/r2 and http://acme.com/fhir/r3. However, this can be problematic because it means that the same record has a different identity depending on the version of FHIR in use - though this can also be useful; it depends on the context.
A server can support multiple versions on the same end-point, if the client specifies which version to support using the fhirVersion mime type parameter:
GET [base]/metadata Accept: application/fhir+json; fhirVersion=3.0
This is a request to return the CapabilityStatement for the server’s support of FHIR Release 3. The client will know that the server doesn’t support R3 if it gets an error in return, or if the capability statement that comes back has a different fhirVersion (which would mean that the server does not support the fhirVersion parameter).
Notes:
--MIME_boundary Content-Type: application/fhir+xml; fhirVersion=1.0
Clients can determine what versions a server supports by using the $versions operation.
Storage
The same technique can be used in a database, or any other kind of storage – just store the mime type (or just the version) alongside the resource. This means that when reading resources, the application knows what version the resource has, and therefore what parser to use, before reading the resource.
There are some circumstances where applications handle ‘naked’ resources – that is, resources where there is no wrapping envelope to carry a mimetype version parameter, nor any suitable parallel location to store the version. The most obvious circumstance is when resources are stored in files, though this may arise in other circumstances due to (legacy) application or protocol design.
When there’s no other alternative, the version has to be in the resources itself, and applications reading the resource have to scan the resource to determine the version and then read the resource as the correct version.
In these cases where the version must be placed in the resource itself, this is done by indicating that the resource conforms to specific version in meta.profile:
{ "resourceType" : "Patient", "meta" : { "profile" : ["http://hl7.org/fhir/3.0/StructureDefinition/Patient"] } }
This technique can be used with all versions of FHIR, including R2 and R3:
FHIR R1 (DSTU 1) | 0.0 |
FHIR R2 (DSTU 2) | 1.0 |
FHIR R3 (STU3, or just R3) | 3.0 |
FHIR R4 (this version) | 4.0 (once published) |
This means that there are 3 different methods for determining version, all of which may be applicable when exchanging data. Implementers are advised to adopt their use in the order documented:
CapabilityStatement
,
a version parameter should be stored alongside the resource, preferably using the mime type parameter documented aboveWhen determining the version, there’s no order of preference between these methods: if the version of a resource or interaction is specified more than one way, the version statements must all agree with each other, or it is an error, and applications can process a request/resource how they wish – usually, with some kind of error.
All parts of the FHIR specification are subject to ongoing change. The types of changes allowed, and the change control process vary, as detailed in the Version Management Policy. Implementers need to be aware of what kind of changes are made and have a strategy for dealing with them. Where possible, implementers should design their solutions to be able to manage changes to the specification and, where necessary, to manage interoperability with systems that may be using different versions of the specification.
A key aspect of the FHIR specification development process is gaining feedback from implementers making use of the specification. As well, the process is conditional on real world implementation in order to move through the maturity cycle. For this reason, all FHIR implementers are encouraged to register their usage here, which captures contact and other information that will allow HL7 to perform appropriate monitoring of FHIR usage. Survey information is confidential and reported in aggregate only. (Note that implementers can advertise their use of FHIR here.
Maturity Level: Normative | Standards Status:Normative |
This page documents the way version change is handled in FHIR. FHIR is a standard, so the way version change is handled is a bit different from an application API. This page describes:
See also Managing FHIR Versions for additional implementer advice about dealing with versions.
FHIR is a standard. In order to be useful, standards need to evolve. At the same time, the evolution of standards needs to be predictable and manageable for the implementation community. This section describes how HL7 develops a standard so that implementers know what to expect as the standard evolves.
HL7 has four descriptive terms that describe the level of stability and implementation readiness associated with different aspects of the specification. They are as follows:
Standard Level | Description |
---|---|
Draft | This portion of the specification is not considered to be complete enough or sufficiently reviewed to be safe for implementation. It may have known issues or still be in the "in development" stage. It is included in the publication as a place-holder, to solicit feedback from the implementation community and/or to give implementers some insight as to functionality likely to be included in future versions of the specification. Content at this level should only be implemented by the brave or desperate and is very much "use at your own risk". The content that is Draft that will usually be elevated to Trial Use once review and correction is complete after it has been subjected to ballot |
Trial Use |
This content has been well reviewed and is considered by the authors to be ready for use in production systems. It has been subjected to ballot and approved as an official standard. However, it has not yet seen widespread use in production across the full spectrum of environments it is intended to be used in. In some cases, there may be documented known issues that require implementation experience to determine appropriate resolutions for. Future versions of FHIR may make significant changes to Trial Use content that are not compatible with previously published content. |
Normative | This content has been subject to review and production implementation in a wide variety of environments. The content is considered to be stable and has been 'locked', subjecting it to FHIR Inter-version Compatibility Rules. While changes are possible, they are expected to be infrequent and are tightly constrained. |
Informative | This portion of the specification is provided for implementer assistance, and does not make rules that implementers are required to follow. Typical examples of this content in the FHIR specification are tables of contents, registries, examples, and implementer advice |
Deprecated | This portion of the specification is outdated and may be withdrawn in a future version. Implementers who already support it should continue to do so for backward compatibility. Implementers should avoid adding new uses of this portion of the specification. The specification should include guidance on what implementers should use instead of the deprecated portion |
Some Normative artefacts contain a few parts labeled as 'Trial Use' even though the artifact itself is labeled 'Normative':
While HL7 prefers to avoid this outcome, there are a number of resources where the overall functionality of the artefact is clearly ready to be labeled as 'normative' while some very specific parts are known not to have the requisite level of implementation experience as the rest of the resource. E.g. Bundle.signature.
Where a Normative resource contains elements marked as trial-use, these elements are clearly marked in the resource definitions. Implementers should be aware that future versions of the FHIR specification may change these parts of the resources (in addition to the other changes allowed under the inter-version compatibility rules. While HL7 will carefully consider the consequences of breaking change to these elements, implementers should be aware that reading/using these elements has the potential to cause breaking change to their applications later.
Note that this same status will arise as a matter of process when new elements are introduced into normative resources in future versions - they will undergo a period of trial use as appropriate.
Note: it is also possible that some resources in the future will be labeled as 'trial use', but contain some elements labeled as 'normative'. There is no resource like this in this specification, though all Trial Use resources contain normative content from Resource and DomainResource, and the Data types.
This release (Release 3) is a Trial Use Specification, though a little of the content (where marked specifically at the top of the page) is Draft. For Release 4, some content is planned to be Normative.
Notes:
The content of this release has been subject to significant review through ballot and other HL7 processes and many aspects of it have been implemented and subjected to interoperability testing through Connectathons and early adoption. However, the degree of testing has varied. Some resources have been well tested in a variety of environments. Others have received relatively little real-world exercise. In general, the infrastructure should be considered to be more stable than the resources themselves. In some cases, there are issues on which input is specifically requested during the Trial Use period (see the Outstanding Issue List, and known issues will arise after publication (refer to the FHIR Change Request tracker for details.) Guidance from early implementation will help address these areas.
All artifacts in this specification are assigned a "Maturity Level", known as FMM (after the well known CMM grades). The FMM level can be used by implementers to judge how advanced - and therefore stable - an artifact is. The following FMM levels are defined:
Draft (0) | the resource or profile (artifact) has been published on the current build. This level is synonymous with Draft |
FMM 1 | PLUS the artifact produces no warnings during the build process and the responsible WG has indicated that they consider the artifact substantially complete and ready for implementation. For resources, profiles and implementation guides, the FHIR Management Group has approved the underlying resource/profile/IG proposal |
FMM 2 | PLUS the artifact has been tested and successfully supports interoperability among at least three independently developed systems leveraging most of the scope (e.g. at least 80% of the core data elements) using semi-realistic data and scenarios based on at least one of the declared scopes of the artifact (e.g. at a connectathon). These interoperability results must have been reported to and accepted by the FMG |
FMM 3 | PLUS + the artifact has been verified by the work group as meeting the Conformance Resource Quality Guidelines; has been subject to a round of formal balloting; has at least 10 distinct implementer comments recorded in the tracker drawn from at least 3 organizations resulting in at least one substantive change |
FMM 4 | PLUS the artifact has been tested across its scope (see below), published in a formal publication (e.g. Trial-Use ), and implemented in multiple prototype projects. As well, the responsible work group agrees the artifact is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes |
FMM 5 | the artifact has been published in two formal publication release cycles at FMM1+ (i.e. Trial-Use level) and has been implemented in at least 5 independent production systems in more than one country |
Normative | the artifact is now considered stable |
Tested across scope means:
The Maturity level is strongly related to stability; the higher the maturity level, the more controls are enforced to restrict breaking changes to the resource. For further information, and discussion, see the FHIR Confluence page.
The maturity model is significantly influenced by the degree and type of implementation activity using an artifact. For this reason, we encourage implementers to register their implementations. A detailed analysis of the basis for the maturity metrics for FHIR artifacts can be found here.
New versions of FHIR will be published on a release cycle of approximately 18-24 months. This frequency is based on the timelines necessary to consult with implementers, to develop and review new content, as well as to undertake the formal balloting and reconciliation processes required for ANSI-approved standards. This release cycle also ensures an opportunity to incorporate implementer feedback from earlier versions of the specification into subsequent versions. Limited-scope releases on a shorter timeline may occur occasionally where necessary to meet implementer needs.
Each new release is assigned a unique version number. The FHIR version policy is based on Semantic versioning, but with some differences due to the fact that FHIR is a specification, not a software API.
There is a single development version of FHIR. This undergoes cycles of development as managed by HL7. Each major cycle of development is concluded by a formal ballot (or more than one), and then a new specification is published. In version control terms, each published specification is a branch off the development trunk, which may then itself undergo further change as HL7 maintains the published specification (though such changes are usually minimal, limited to necessary technical corrections or security alerts).
Each FHIR version is identified by a string composed from 4 parts: publication.major.minor.revision.
publication |
|
major |
|
minor |
|
revision |
|
Additional notes:
The FHIR version is usually known implicitly, but can be specified/determined by one of three methods:
For further information, see Managing Multiple FHIR Versions.
The intent of these rules is to ensure that applications that are conformant to an existing specification are also conformant to subsequent versions. In practice, there are many subtle issues around inter-version change, and the exact rules are subject to further clarification based on feedback from implementers.
The following kinds of changes may be made to the specification:
NOTE: The examples provided as part of this specification are never substantive. While every effort is made to ensure that FHIR examples are correct, changes to the examples in the specification are not considered substantive.
Content with a status of Draft or Trial Use can change - including Breaking Changes - from version to version, subject to the rules described by the Maturity Process. There are no rules for maintaining any sort of compatibility between versions for content with these statuses, though of we will only make breaking changes based on feedback from the community.
Once an artifact achieves Normative status, specific rules come into play around inter-version compatibility. These rules have implication for both forward and backward compatibility and are intended to allow implementations to exercise FHIR interfaces and process the content of FHIR resources safely while exchanging data between systems using different versions of FHIR.
Forward compatibility means that content that is conformant in an old release will remain conformant with future versions. Once normative, FHIR's rules try to enforce forward compatibility. However, that doesn't guarantee that all old systems will interoperate with future systems.
Backward compatibility means that instances created against future versions of the specification will interoperate with older versions of the specification. This is not guaranteed by FHIR, though there are strategies systems can adhere to that will increase their chances of such interoperability. Specifically, when dealing with content from a system supporting an unknown normative version and wishing to maximize backwards compatibility, applications SHOULD:
However, in a healthcare context, many implementers are unwilling to consider some of these steps because of concerns about clinical risk or technical limitations in their software (e.g. schema based processing).
Category | Allowed changes |
---|---|
Resources | New artifacts resources may be introduced. Existing resources will not have their names changed |
Artifacts (resources, profiles, code systems, etc.) | New artifacts including new resources and data types may be introduced. Existing artifacts will not have any computable identifiers (e.g. resource names) changed. Artifacts may be deprecated |
Elements | New optional elements and/or content (e.g. XML attributes, etc.) may be introduced at any location in resource and data type structures provided they do not constitute "isModifier" elements. However, the names, path and meaning of previously existing data elements will not be changed. This means there will be no change to resource names and no changes to names assigned to slices and other elements within profiles. |
Cardinality | Minimum element cardinalities will not be changed. Upper cardinality may change from 1 to * only in circumstances where all elements except for the first repetition can be safely ignored. Note that this may change the path to the element in some syntaxes (e.g. JSON). This may mean that an order is assigned to the repeating items or that there is no preference as to which element is retained. Systems should follow the rules above for unexpected elements. |
Descriptions | Descriptive information about a resource - short labels, definitions, usage notes, aliases, examples, rationale, mappings, etc. may be updated or revised to provide additional clarity or guidance, but not in such a manner as to invalidate a reasonable interpretation of the previously documented use of an element. (This does not preclude fixing obvious errors.) |
Value Sets and Code Systems |
The definition of any value set that is marked as immutable will never change. The expansions for immutable value sets may still change if no "stable date" is declared and the value set does not restrict code system and/or value set references to specific versions and the codes in the referenced code system(s) or value set(s) change. For non-immutable value sets:
For both immutable and non-immutable value sets, additional designations may be declared. Normative CodeSystems whose content is generated from a mix of normative and non-normative contents may break these rules. For example, the code system containing the list of all resources may have codes removed or renamed as non-normative resources are removed or renamed. These expectations only apply to Value Sets and Code Systems maintained as part of the FHIR specification. HL7 cannot enforce these rules on terminology artifacts maintained by other authorities - e.g. UCUM unit codes, ISO language codes, etc |
Terminology Bindings |
|
Data Types |
Except as described in the preceding paragraph, Data types will not be removed or changed except as allowed above for elements. New data types may be introduced. Types declared on existing elements will not be
removed or changed, except for the special case that string may be changed to markdown .
Additional data types may be added to elements which are already expressed as a choice of data types only if those elements are optional (minimum cardinality = 0).
|
Value Constraints | The allowed list of Data types will not be added, removed or changed. Invariants, regular expressions, fixed values and patterns will not be added, removed or changed. |
Flags | The Is Modifier and Is Summary flags will not be changed. |
Slicing | Slicing rules and aggregation characteristics will not be changed. |
Search Criteria | Search criteria may be added but not removed or renamed. Existing criteria will not have their type or path changed or have their description altered in any way that would invalidate the reasonable behavior of existing systems (with the exception of correcting obvious errors). |
Operations | New operations may be defined but operations will not be removed or renamed. Existing parameters will not be removed or renamed, nor may their type or lower cardinality be changed. Upper cardinality may be changed from 1 to *. (Systems should ignore unexpected repetitions.) Additional optional parameters may be introduced. Changes to operations that would violate the preceding constraints will be handled by defining new operations and, potentially, deprecating the old operations. |
Restful interface | Existing endpoints will not be renamed or removed, nor have their expected behavior changed in a manner that would cause reasonable systems designed against prior versions to be non-interoperable. Additional endpoints and interactions may be introduced. |
Profiles and extension definitions | Profile structure, extension definitions and search criteria definitions will not be removed or have their URIs changed. New profile structures, extension definitions and search criteria definitions may be introduced. Profiles may have their statuses changed to "retired". Profiles referenced by data elements for structures or data types may be replaced with a reference to a distinct profile that is "compatible" with the previously referenced profile according to these forward and backward compatibility rules. |
Capability Statements | Within the CapabilityStatements for defined FHIR Services or 'core' implementation guides, additional operations may be added. These additions might be optional (MAY/SHOULD) or mandatory (SHALL). Note that the introduction of mandatory operations would break forwards compatibility and will only occur with community consultation. |
Implementation Guides | Additional artifacts can be added and artifacts can be changed. The list of global profiles will not change |
References | Where one conformance resource points to another (e.g. CapabilityStatement to profile, profile to profiles, profile to value set, etc.), the reference may change to point to a newer version of the conformance resource or to a distinct conformance resource so long as the content of the newly referenced resource adheres to the compatibility rules with respect to the previously referenced version. |
NOTE: In rare circumstances, HL7 may approve changes that technically break one of the above rules in situations where there is a high level of confidence that the change will not impact existing implementers. Such deviations from these declared rules will involve broad notification, extensive community consultation and reviews by multiple levels of HL7 governance processes.
Once content is normative, there is a process for removing it from the standard by marking it as
deprecated
or withdrawn
(from the HTML 4.0 Standard):
Deprecated | Systems should continue to support the artefact/feature/concept, but are discouraged from making use of it |
Withdrawn | Documented for historical purposes, no longer supported |
The specification will provide guidance with deprecated materials showing how to avoid using them.
Deprecated
materials are eligible to be balloted to be withdrawn
two years after their deprecated
status is published.
The computable artifact labels (e.g. codes, element names, urls, etc) associated with withdrawn materials SHALL not be used in future versions of HL7 specifications. Materials marked "deprecated" may have that marking removed as part of a subsequent ballot at a later moment, while withdrawn materials SHALL NOT.
The following artefacts are deprecated in this version of FHIR:
Additional discussion on inter-versioning issues can be found here: https://confluence.hl7.org/display/FHIR/Interversion+Compatibility.
Regardless of the degree of prior implementation, all aspects of the FHIR specification are potentially subject to change while an artifact has a status of Draft or Trial Use. These changes may be minor (clarifications of definitions, etc.) or major (refactoring of resources, changes to serialization rules, eliminating or adding data types, etc.) There is no commitment to backward or forward compatibility during the trial use process until content is normative. Changes will not be made without cause, however the interests of long-term implementability will generally trump the impact on early adopters when determining what changes should be made. This balance will shift more towards early adopters as maturity levels increase. I.e. Impact on existing implementations will be weighted more highly for an FMM-level 5 artifact than they would for an FMM-level 1 artifact.
Implementers who are willing to accept the risk of change (perhaps for the benefit of early implementation experience, first mover advantage and the ability to leverage FHIR's intrinsic benefits) are encouraged to implement those parts of FHIR that are early in the maturity cycle in real-world systems. However, those implementers should be aware that local adaptations may be necessary to meet real-world requirements. Furthermore, such implementers should architect their solutions to be tolerant of changes to the specification and, where necessary, to manage interoperability with systems that may be using different versions of the specification or different local adaptations.
During the Trial Use period, requests for change may be submitted using the HL7 issue tracker which can be found here. Where possible, updates to the "development" version of the specification will be made in a timely fashion. Implementers should be aware that the changes are not considered "official" until such time as they are balloted and approved as part of a subsequent Trial Use or Normative publication. Change requests might be fixes to allow implementation, clarifications or enhancements. In addition, HL7 will be developing and introducing additional resources and profiles as part of the FHIR specification.
SDOs and regulatory bodies that are interested in making use of the FHIR specification should feel free to do so, but should consider and plan for the possibility that the specification will evolve and change prior to becoming Normative.
A key aspect of the FHIR specification development process is gaining feedback from implementers making use of the specification. As well, the process is conditional on real world implementation in order to move through the maturity cycle. For this reason, all FHIR implementers are encouraged to register their usage here, which captures contact and other information that will allow HL7 to perform appropriate monitoring of FHIR usage. Survey information is confidential and reported in aggregate only.
Many implementations need to convert resources from one FHIR version to another. Once resources become normative (once sufficiently mature and stable), converting resources forwards from past versions is not needed. Converting back to older versions presents a challenge, however, in that the newer version may add additional elements that are not present in the older version. In some cases, the elements are simply irrelevant since the requirements they represent are not in scope for older applications, but in other cases, it is necessary to represent the data in order to cater for round-tripping.
A more complex problem arises with resources that are not yet stable (early in the maturity process). If applications have implemented less stable resources, not only do they have the problem of new elements for new requirements, the specification may change in either compatible or incompatible ways, and it may be necessary to carry data elements from past versions forward in order to allow seamless round-tripping.
In order to help implementers with this problem, any element defined in any version of FHIR is automatically assigned an extension URL that uniquely identifies the element and can be used in the relevant FHIR version. The extension URL for an element can automatically be derived:
http://hl7.org/fhir/[version]/StructureDefinition/extension-[Path]
where [version] is taken from this list:
This technique can be used with all versions of FHIR, including R2 and R3:
FHIR DSTU2 | 1.0 |
FHIR R3 (STU3, or just R3) | 3.0 |
FHIR R4 (this version) | 4.0 (once published) |
Note that this extension framework only applies back to DSTU2. The [Path] is actually the ElementDefinition.id from the relevant StructureDefinition for the element. This leads to URLS like the following:
http://hl7.org/fhir/4.0/StructureDefinition/extension-Bundle.signature | R4 Signature Element on Bundle |
http://hl7.org/fhir/3.0/StructureDefinition/extension-Patient.animal.species | STU3 Species Element on Patient |
http://hl7.org/fhir/1.0/StructureDefinition/extension-ValueSet.extensible | DSTU2 ValueSet.extensible |
Implementers should be aware of the following issues when using these extensions:
This table shows the mapping between primitive data types across versions:
R4 | R3 | DSTU2 |
base64Binary | base64Binary | base64Binary |
boolean | boolean | boolean |
canonical | (uri) | (uri) |
code | code | code |
date | date | date |
dateTime | dateTime | dateTime |
decimal | decimal | decimal |
id | id | id |
instant | instant | instant |
integer | integer | integer |
markdown | markdown | markdown |
oid | oid | oid |
positiveInt | positiveInt | positiveInt |
string | string | string |
time | time | time |
unsignedInt | unsignedInt | unsignedInt |
uri | uri | uri |
url | (uri) | (uri) |
uuid | uuid | (id) |
Formal Definitions for extensions:
Note for balloters: these packages will be created when R4 is finalized. Until then, these are broken links.
While implementation of this Trial Use release is occurring, development will be progressing on the next release. This next release will include additional resources, profiles and quality enhancements over the current release. It will also incorporate fixes for issues raised with the FHIR issue tracker. It may be useful for implementers of the STU to review the development release to get a sense of what changes are likely coming and perhaps to find more robust definitions and guidance than are available in the first release. The FHIR development release can be found at build.fhir.org. Some implementers who are dependent on content that exists in a draft release may choose to implement based on a particular snapshot of the development release, though in doing so, they will limit their potential communication partners and would not be considered to be completely FHIR conformant.
The next major publication of FHIR will be Release 4. It is our hope that this release will include the transition of some of the content of the specification to Normative. This should include many of the core infrastructure resources (e.g. StructureDefinition, ValueSet as well key pages such as the XML and JSON syntaxes, RESTful protocol, etc. It should also include at least a few of the administrative resources such as Patient. Much content, including most if not all clinical and business resources, will remain at the Trial Use level as they are not expected to meet the criteria for Normative.
The anticipated timeline for Release 4 involves a finalization of scope by the end of 2017, balloting in April of 2018 and publication around October 2018. The specific timing may vary based on implementer feedback and the volume of contents received during the ballot process. More information on plans for Release 4 can be found on the HL7 product director's blog. (Subscribing to this blog is a good way to keep current on significant events in FHIR development, including ballot and publication timelines.)
There will be additional releases of FHIR with a frequency of between 18 and 24 months for the foreseeable future. These releases will include new content (e.g. in the public health, financial or clinical research spaces), revisions reflecting implementer feedback and increasing maturity on Trial Use artifacts and the migration of additional content to normative status. As well, HL7 will gradually shift focus to providing additional guidance through the publication of implementation guides and profiles where consensus can be found at the international level.
FHIR Infrastructure Work Group | Maturity Level: N/A | Standards Status: Informative |
This page is deprecated and will be a removed in a future version of this publication. Instead, see the FiveWs pattern.
Concise
Full
Maturity Level: 2 | Standards Status:Trial Use |
TODO: Discussion (or reference to one) on Polling and Subscription
This is by far the most common pattern in FHIR for simple changes as it requires the least overhead. However, it covers only automated responses, and does not support any actual workflows of more than one step. If human processing is involved in the request execution, then this approach won't suffice. This approach is listed here to make sure that implementers consider whether they can make this one work first before falling back to one of the more sophisticated patterns.
???
basedOn
link to the 'request' resource that the action
was performed in fulfillment of.Use this approach when there's no ability to have queue servers and no support/need for complexity of Task, polling or pub/sub (and no need for negotiation or the ability for the filler to say "no"). This is a pseudo-messaging architecture that doesn't actually use messaging architecture.
This pattern could be used when there's no support/need for complexity of Task, usually for simple two step workflows. This is a more typically RESTful approach where data resides on the server "owned" by the data creator and is accessed by other systems.
TODO: needs review and update
Existing messaging infrastructure (e.g. v2 LTP, MLTP, WSI Web Services, Direct, VISA, REST, etc.) and a need to stay consistent with that architecture
TODO: Needs review, update and more work - there's not a lot of experience using FHIR services to manage the fulfillment process
TBD
TODO: needs review and update. Possibly add options about using messaging and/or services instead of polling/subscription in above scenarios
Maturity Level: 2 | Standards Status: Trial Use |
As described in previous sections, many FHIR resources can be used within workflows without using FHIR to manage the execution of the workflows. When we want to manage workflow execution with FHIR, there are several mechanisms available. In addition to managing workflow with FHIR, there are also cases where management of workflow execution is not necessary, and supporting workflow becomes simply the use of the resource patterns in an ad-hoc fashion. In deciding how best to interoperate around workflow with FHIR, there are several considerations:
The answers to these (and other) questions will guide the selection of communication patterns to be used for a specific interoperability use case. It is recommended that domain workgroups analyze the support for workflow execution within their domains and provide recommendations for an appropriate subset of patterns, with a discussion on where and how to use them. Implementation guides, by their nature, should prescribe which patterns to use for workflow execution management.
This section highlights some of the more common patterns and identifies their characteristics and limitations and provides recommendations on when each approach may be most useful or relevant. Please note that this list of patterns is not exhaustive. Patterns can be combined in various ways and there are likely some possibilities we haven't thought about yet (feel free to submit additional patterns using the 'submit a change' link at the bottom of the page). As well, the recommendations given here are just that - recommendations. Implementers are free to choose which patterns they wish to support. Because of this, tight interoperability around workflow execution (as with any other tight interoperability using FHIR) will depend on communicating participants doing some up-front negotiation around how they plan to support workflow execution or all communicating partners will need to adhere to an implementation guide that sets out clear interoperability expectations.
Prior to reviewing this list of options, readers are encouraged to be familiar with the following pages and resources: REST, messaging, operations, services and the Subscription resource.
The scenarios used to illustrate the patterns below make use of a few conventions:
One of the key distinguishing characteristics in the patterns below is whether the pattern supports the tracking of the workflow's state by both the placer and the filler. The workflow state is represented by the Task resource. The Task state machine, which is also presented here, shows the use of Task.status to represent the general infrastructure state of the Task resource.
The combination of Task.status, Task.statusReason and Task.businessStatus provide the mechanism for tracking the workflow state. The following two examples illustrate how that could be accomplished with regards of specific workflows. Note that these examples avoid any specificity on where the described resources exist, or any reference to a specific communication pattern. The goal of the examples is to demonstrate the use of the Task attributes to represent the workflow state.
The following table shows the steps for a simple blood test order, and the corresponding values of the Task attributes. A lot of details on other attributes have been omitted in order to focus on the state changes.
Workflow step | Task.status | Task.statusReason | Task.businessStatus |
---|---|---|---|
Provider orders a blood test for a patient. A ServiceRequest resource is created to represent the order, and a Task resource is created to represent the request to the lab. Task.basedOn points to the ServiceRequest instance. | Requested | New order | Ordered |
The lab accepts the order. | Accepted | Able to perform the test. | Accepted |
The patient is at the lab, and blood is drawn. | In progress | Obtained the specimen | Specimen available |
Work on the blood sample is in progress, preliminary results are available, a DiagnosticReport resource is created, and Task.output.value[1] references the DiagnosticReport resource. | In progress | Preliminary results available | Preliminary results |
Final results are available | Complete | Final results are available | Final results |
The following table shows the steps for a referral workflow, and the corresponding values of the Task attributes. A lot of details on other attributes have been omitted in order to focus on the state changes.
Workflow step | Task.status | Task.statusReason | Task.businessStatus |
---|---|---|---|
Provider A is seeing a patient with a specific complaint. Based on the exam, Provider A refers the patient to a specialist at clinic B. It is an urgent referral, requesting to see the specialist within 4 days. A ServiceRequest resource is created to represent the referral order, and a Task resource is created with Task.priority set to Urgent, and Task.restriction.period.end set to 4 days in the future. | Requested | New referral | Referred |
Clinic B receives the referral and puts it on the urgent queue to be reviewed. | Received | Received by organization | Pending |
Upon reviewing the referral, the clinic determines they have no capacity to see the patient within the specified time period, and they decline the referral. | Rejected | Provider unavailable | Declined |
Provider A changes the referral request to clinic C. This creates a new Task resource, with the appropriate information | Requested | Changed the referred to provider | Referred |
Clinic C accepts the referral and it is placed on a scheduler's queue. | Accepted | Able to provide the service. | Accepted |
An appointment is scheduled for the patient at Clinic C. | In progress | Appointment scheduled | Scheduled |
Soon after the appointment is scheduled, the patient calls provider A to ask for a different location for the referral appointment, as he lost his transportation, and he cannot reach Clinic C. The provider requests a cancel for the referral. | Suspended | Patient unable to make appointment. | Cancel requested |
Clinic C confirms the cancellation of the existing task. |
In progress Failed |
Referral cancelled | Cancelled as requested |
Provider A changes the referral to Clinic D, which is located close to where the patient lives, and can be conveniently reached using public transportation. This creates a new Task resource, with the appropriate information. | Requested | Changed the referred to provider | Referred |
Clinic D accepts the referral and it is placed on a scheduler's queue. | Accepted | Able to provide the service. | Accepted |
An appointment is scheduled for the patient at Clinic D. | In progress | Appointment scheduled | Scheduled |
Patient is seen at Clinic D. A diagnosis is made by the specialist, a prescription is given, and a follow-up appointment is made at clinic D. Task.output.value[1] references a Compositions resource, which contains the encounter summary. | In progress | Intermediary consultation note available | Preliminary notes |
Patient comes for follow-up appointment at clinic D. The specialist is satisfied by the progress the patient has made and creates the final consultation note. Task.output.value[2] references a Compositions resource, which contains consultation note. | Completed | Final consultation note available | Final notes |
The patterns that facilitate the execution of workflow using the Task resource are grouped in the Workflow Management Patterns section. The patterns where no Task resource is used are grouped in the Ad-hoc Workflow Patterns section. The list of patterns is as follows:
TODO: Insert Jose's decision tree here?
Maturity Level: 2 | Standards Status:Trial Use |
Future home for examples
Maturity Level: 2 | Standards Status:Trial Use |
TODO: Discussion (or reference to one) on Polling and Subscription
Placer and filler may need to be able to communicate directly (i.e. know each other's respective endpoints)
Lab order to known performer
A provider orders a bilirubin test for a patient, to be done at the provider's facility lab....
"Open" lab order
A patient is scheduled for their physical, and the provider sends her a secure message to have a fasting blood test performed before the office visit. The message has a link to a requisition, and a list of possible lab locations where the test can be done. The patient chooses a lab location near her place of employment and a test is scheduled. The lab gets the requisition from the patient and, using the information on how to retrieve the Task from the provider's system, claims the test to be performed...
Outpatient prescription
A patient is suffering from a poison ivy rash and is prescribed a steroid medication to manage the reaction. The provider asks the patient for his preferred pharmacy and creates the Task at the specified pharmacy's system. The patient is running late and by the time he arrives at the pharmacy, it is closed. He calls the clinic where the provider practices and requests that the pharmacy where the order is to be fulfilled is changed to one that is open around the clock. The staff at the clinic cancels the Task at the original pharmacy and creates a new Task at the requested new one. By the time the patient arrives at the new pharmacy, the medication is ready for pickup. Once the request is fulfilled, the clinic receives the notification that the Task is complete and the prescription is also marked as complete.
TODO: Still needs review and update
Appropriate in environments that have a workflow engine that takes on responsibility for ensuring fulfillment
Outpatient referral
A patient is seen by her Primary Care Provider (PCP) for shortness of breath and the provider decides to refer her to a cardiologist. Because of the referral, the provider's system creates ServiceRequest resource and POSTs a Task resource to a cardiologist's practice system, requesting a referral. This places the referral request on a referral coordinator's work list to review. Upon accepting the referral, the Task is updated as accepted and a new sub-Task, referencing both the ServiceRequest and the Task created by the provider's system, is created on the provider's system. The patient gets an appointment with the cardiologist and the sub-Task is updated with that information, allowing the provider's system to inform the provider of the change.
The patient misplaces the information about the appointment and misses the visit with the cardiologist. The cardiologist's system updates the sub-Task to indicate the no-show and the PCP is alerted of the missed appointment. The provider's staff gets hold of the patient and schedules another appointment for her with the cardiologist. Because of the cardiologist's system scheduling the appointment, the sub-Task is updated with that information. The patient is seen and the sub-Task is updated accordingly. The cardiologist document the findings about the patient and updates the sub-Task as complete, adding references to the resources representing the findings. The PCP is alerted of the updates and marks the referral as complete, which updates the original Task and the ServiceRequest as complete as well.
TODO: needs more details
Appropriate when existing messaging infrastructure can be used (e.g. HL7 over HTTP, v2 LTP, MLTP, WSI Web Services, Direct, VISA, REST, etc.), and a need to stay consistent with that architecture.
TODO: This scenario needs work - there's not a lot of experience using FHIR services to manage the fulfillment process
TBD
TODO: needs review and update. Possibly add options about using messaging and/or services instead of polling/subscription in above scenarios
This is a variation ofOption H, where the Workflow broker is essentially merged with the fulfiller. It still allows the placer to only use a POST of the request, and be made aware of the changes to the other resources via subscription or polling.
Work Group Standards Status: Informative |
The workflow module focuses on the coordination of activities within and across systems. This includes three primary aspects:
Infrastructure |
|
Scheduling |
|
Clinical Process |
|
Workflows can be performed through direct posting of resources to a target server (combined with a specific tag), by using the Task resource, through the use of messaging or via FHIR services. This specification includes a workflow page that describes the concepts underlying the discussion of workflows, and points to a number of different communication and architectural workflow patterns.
In addition to the Task resource, this specification defines three logical models - Definition, Request and Event that define the patterns for resources that are typically involved in workflow. These patterns include elements defining common attributes of each type of resource as well as relationships between them. These relationships are summarized on the workflow page, along with a complete list of resources that follow (or are hoped to soon follow) the request and event patterns.
Finally the PlanDefinition and ActivityDefinition resources combine to support the creation of protocols, orders sets, guidelines and other workflow definitions by describing the types of activities that can occur and setting rules about their composition, sequencing, interdependencies and flow.
Workflow manifests in many places in the healthcare environment:
FHIR provides multiple ways to enable these scenarios (and many others). Common mechanisms, along with their pros and cons can be found in the workflow sections on patterns.
Resources related to workflow need to adhere to the same security and privacy guidelines that apply to all FHIR resources, including specific considerations for those that may contain personally-identifying information. There are a couple of additional security and privacy considerations specific to workflow:
1. Some workflows are ad-hoc without pre-defined participants or flows. These can be challenging for security and privacy processes to manage appropriately
2. Workflow can drive automated behavior. I.e. The mere existence of an electronic record can cause information to flow, procedures to be performed, records to be changed and money to be transferred, potentially without any intervention, oversight or sanity checking by a human being. As such, even greater care must be taken to ensure that:
For more general considerations, see the Security and Privacy module.
Initial work has taken place on aligning most (though not yet all) resources with the Definition, Request and Event patterns. In the lead-up to R4, we'll be looking to align the remaining resources, reviewing and potentially increasing the consistency of existing alignments (where beneficial to implementers) and examining the potential for exposing alignment with the patterns in a computably useful manner (e.g. as interfaces).
Work will continue on the workflow patterns, including vetting the patterns against various clinical scenarios and enhancing pattern documentation. We also hope to examine both messaging and services in more detail with further guidance about when and how such mechanisms should be used for workflow and how they relate to the Task resource. As well, we'll examine the possibility for developing "standardized" workflows for certain domains and how such patterns might be documented. We will look for implementer feedback to guide this work.
The PlanDefinition and ActivityDefinition resources will continue to evolve based on feedback from the implementer community. We'll explore using them in a variety of ways, including clinical order sets, medication protocols, workflow protocols, clinical pathways, administrative protocols, etc.
Additional topics for future work include: