Maturity Level: N/A | Standards Status:Informative |
This page lists all search parameters defined as part of this specification. For further details regarding using search parameters, see searching on the RESTful API.
All resources have the canonical URL http://hl7.org/fhir/SearchParameter/[id] where [id] is taken from the table below. You can download XML and JSON source for this page.
Parameter | Type | Id | Description | Paths (Expression) |
---|
Work Group Standards Status:Informative |
The Security and Privacy Module describes how to protect a FHIR server (through access control and authorization), how to document what permissions a user has granted (consent), and how to keep records about what events have been performed (audit logging and provenance). FHIR does not mandate a single technical approach to security and privacy; rather, the specification provides a set of building blocks that can be applied to create secure, private systems.
The Security and Privacy module includes the following materials:
Resources | Datatypes | Implementation Guidance and Principles |
The following common use-cases are elaborated below:
FHIR is focused on the data access methods and encoding leveraging existing Security solutions. Security in FHIR needs to focus on the set of considerations required to ensure that data can be discovered, accessed, or altered only in accordance with expectations and policies. Implementation should leverage existing security standards and implementations to ensure that:
For general security considerations and principles, see Security. Please leverage mature Security Frameworks covering device security, cloud security, big-data security, service-to-service security, etc. See NIST Mobile Device Security and OWASP Mobile Secuity. These security frameworks include prioritized lists of most important concerns.
Privacy in FHIR includes the set of considerations required to ensure that individual data are treated according to an individual's Privacy Principles. FHIR includes implementation guidance to ensure that:
Use case: A FHIR server should ensure that API access is allowed for authorized requests and denied for unauthorized requests.
Approach: Authorization details can vary according to local policy, and according to the access scenario (e.g. sharing data among institution-internal subsystems vs. sharing data with trusted partners vs. sharing data with third-party user-facing apps). In general, FHIR enables a separation of concerns between the FHIR REST API and standards-based authorization protocols like OAuth. For the use case of user-facing third-party app authorization, we recommend the OAuth-based SMART protocol see Security: Authentication as an externally-reviewed authorization mechanism with a real-world deployment base — but we note that community efforts are underway to explore a variety of approaches to authorization. For further details, see Security: Authorization and Access Control.
Use-Case: When a user has restricted rights but attempts to do a query they do not have rights to, they should not be given the data. Policy should be used to determine if the user query should result in an error, zero data, or the data one would get after removing the non-authorized parameters.
Example: Using _include or _revinc to get at resources beyond those authorized. Ignoring (removing) the _include parameter would give some results, just not the _include Resources. This could be silently handled and thus give some results, or it could be returned as error.
Use case: "Access to protected Resources are enabled though user Role-Based, Context-Based, and/or Attribute-Based Access Control."
Approach: Ensure that the level of assurance for identity proofing reflects the appropriate risk, given the issued party’s exposure to health information. Users should be identified and should have their Functional and/or Structural role declared when these roles are related to the functionality the user is interacting with. Roles should be conveyed using standard codes from Security Role Vocabulary.
A purpose of use should be asserted for each requested action on a Resource. Purpose of use should be conveyed using standard codes from Purpose of Use Vocabulary.
When using OAuth, the requested action on a Resource for specified one or more purpose of use and the role of the user are managed by the OAuth authorization service (AS) and may be communicated in the security token where jwt tokens are used. For details, see Security: HCS vocabulary.
Use case: "A FHIR server should keep a complete, tamper-proof log of all API access and other security- and privacy-relevant events".
Approach: FHIR provides an AuditEvent resource suitable for use by FHIR clients and servers to record when a security or privacy relevant event has occurred. This form of audit logging records as much detail as reasonable at the time the event happened. The FHIR AuditEvent is aligned and cross-referenced with IHE Audit Trail and Node Authentication (ATNA) Profile. For details, see Security: Audit.
Use case: "A Patient should be offered a report that informs about how their data is Collected, Used, and Disclosed.".
Approach: The AuditEvent resource can inform this report.
There are many motivations to provide a Patient with some report on how their data was used. There is a very restricted version of this in HIPAA as an "Accounting of Disclosures", there are others that would include more accesses. The result is a human readable report. The raw material used to create this report can be derived from a well recorded 'security audit log', specifically based on AuditEvent. The format of the report delivered to the Patient is not further discussed but might be: printed on paper, PDF, comma separated file, or FHIR Document made up of filtered and crafted AuditEvent Resources. The report would indicate, to the best ability, Who accessed What data from Where at When for Why purpose. The 'best ability' recognizes that some events happen during emergent conditions where some knowledge is not knowable. The report usually does need to be careful not to abuse the Privacy rights of the individual that accessed the data (Who). The report would describe the data that was accessed (What), not duplicate the data.
Some events are known to be subject to the Accounting of Disclosures report when the event happens, thus can be recorded as an Accounting of Disclosures - See example Accounting of Disclosures. Other events must be pulled from the security audit log. A security audit log will record ALL actions upon data regardless of if they are reportable to the Patient. This is true because the security audit log is used for many other purposes. - See Audit Logging. These recorded AuditEvents may need to be manipulated to protect organization or employee (provider) privacy constraints. GIven the large number of AuditEvents, there may be multiple records of the same actual access event, so the reporting will need to de-duplicate.
Use case: "Documentation of a Patient's Privacy Consent Directive - rules for Collection, Use, and Disclosure of their health data."
Approach: FHIR provides a Consent resource suitable for use by FHIR clients and servers to record current Privacy Consent state. The meaning of a consent or the absence of the consent is a local policy concern. The Privacy Consent may be a pointer to privacy rules documented elsewhere, such as a policy identifier or identifier in XACML. The Privacy Consent has the ability to point at a scanned image of an ink-on-paper signing ceremony, and supports digital signatures through use of Provenance. The Privacy Consent has the ability to include some simple FHIR centric base and exception rules.
All uses of FHIR Resources would be security/privacy relevant and thus should be recorded in an AuditEvent. The data access that qualifies as a Disclosure should additionally be recorded as a Disclosure, see Disclosure Audit Event Example.
For Privacy Consent guidance and examples, see Consent Resource.
Use case: "All FHIR Resources should be capable of having the Provenance fully described."
Approach: FHIR provides the Provenance resource suitable for use by FHIR clients and servers to record the full provenance details: who, what, where, when, and why. A Provenance resource can record details for Create, Update, and Delete; or any other activity. Generally, Read operations would be recorded using AuditEvent. Many Resources include these elements within; this is done when that provenance element is critical to the use of that Resource. This overlap is expected and cross-referenced on the W5 report. For details, see Provenance Resource.
Use case: "For any given query, need Provenance records also."
Approach: Given that a system is using Provenance records.
When one needs the Provenance records in addition to the results of a query on other records (e.g. Query on MedicationRequest),
then one uses reverse include to request that all Provenance records also be returned.
That is to add ?_revinclude=Provenance:target
.
For details, see _revinclude.
Use case: "Digital Signature is needed to prove authenticity, integrity, and non-repudiation."
Approach: FHIR Resources are often parts of Medical Record or are communicated as part of formal Medical Documentation. As such there is a need to cryptographically bind a signature so that the receiving or consuming actor can verify authenticity, integrity, and non-repudiation. This functionality is provided through the signature element in Provenance Resource. Where the signature can be any local policy agreed to signature including Digital Signature methods and Electronic Signature. For details, see Security: Digital Signatures.
Digital Signatures bind cryptographically the exact contents, so that any changes will make the Digital Signature invalid. When a Resource is created, or updated the server is expected to update relevant elements that it manages (id, lastupdated, etc.). These changes, although expected of normal RESTful create/update operations, will break any Digital Signature that has been calculated prior. One solution is to create the Digital Signature after the REST create operation completes, one must first confirm that the resulting created/updated Resource is as expected, then the Digital Signature is formed.
A variation of this happens in Messaging, Documents, and other interaction models. For details, see Ramifications of storage/retrieval variations
De-Identification is inclusive of pseudonymization and anonymization; which are the processes of reducing privacy risk by eliminating and modifying data elements to meet a targeted use-case.
Use-Case: "Requesting Client should have access to De-Identified data only."
Trigger: Based on an Access Control decision that results in a permit with an Obligation to De-Identify, the Results delivered to the Requesting Client would be de-identified.
Consideration: This assumes the system knows the type and intensity of the de-identification algorithm, where de-identification is best viewed as a process, not an algorithm - a process that reduces Privacy risk while enabling a targeted and authorized use-case.
Modifying an element: The de-identification process may determine that specific elements need to be modified to lower privacy risk. Some methods of modifying are: eliminating the element, setting to a static value (e.g. "removed"), fuzzing (e.g. adjusting by some random value), masking (e.g. encryption), pseudonym (e.g. replace with an alias), etc. Narrative and Attachment elements present particularly difficult challenges. See standards below for further details.
Discussion:
Obviously the most important elements for de-identification are names and identifiers. FHIR resources have
many different types of ids and identifiers that serve different purposes. Some (id
s) are the basis for internal
links between different resources, while identifiers are mainly - but not exclusively - for correlating with external data sources.
Strategies for de-identification need to consider whether re-identification with the source system is a problem,
in which case ids will need to be modified - and consistently across the resource set being de-identified.
External identifiers will mostly need to be removed, but even then, where they are used for internal references
within the resource set, they'll need to be changed consistently.
Then, there is the question of where to make the de-identification changes. For example, the Observation Resource has a subject element that mostly refers to a Patient resource. Should it be removed? or left and the Patient resource it refers to be de-identified? Or it be updated to a new patient resource randomly or consistently? There are many other Reference elements on Observation that can easily be used to navigate back to the Subject; e.g., Observation.context value of Encounter or EpisodeOfCare; or Observation.performer. These also need to be de-identified, and it will depend on the intended use of the data whether these all need to be consistent with each other.
Some identifiers in Observation Resource:
Emphasis: The .specimen is a direct identifier of a particular specimen; and would be an indirect identifier of a particular person. There is a ramification of having the specimen identifier. One solution is to create pseudo specimen resources that will stand-in for the original specimen resource. This pseudo specimen management is supplied by a trusted-third-party that maintains a database of pseudo-identifiers with authorized reversibility.
Care should be taken when modifying an isModifier elements, as the modification will change the meaning of the Resource.
In practice, then, the de-identification process depends on the intended use of the data, the scope of the data being extracted, and the risk associated with the release of the data (e.g. data released into the public domain has a different risk than internal sharing of data within a tightly managed organization with strong information security policies.
Security-label: The resulting Resource should be marked with security-label to indicate that it has been de-identified. This would assure that downstream use doesn't mistake this Resource as representing full fidelity. These security-labels come from the Security Integrity Observation ValueSet. Some useful security-tag vocabulary: ANONYED, MASKED, PSEUDED, REDACTED
Further Standards: Health: ISO Pseudonymization, NIST IR 8053 - De-Identification of Personal Information, IHE De-Identification Handbook, DICOM (Part 15, Chapter E)
Use-Case: There are times when test data is needed. Test data are data that is not associated with any real patient. Test data are usually representative of expected data that is published for the purpose of testing. Test data may be fully fabricated, synthetic, or derived from use-cases that had previously caused failures.
Trigger: When test data are published it may be important to identify the data as test data.
Consideration: This identification may be to assure that the test data is not misunderstood as real data, and that the test data is not factored into statistics or reporting. However, there is a risk that identifying test data may inappropriately thwart the intended test that the data are published to test.
Discussion:
Test data could be isolated in a server specific to test data.
Test data could be intermingled with real-patient data using one or both of the following methods:
Considerations: Note there is a risk when co-mingling test data with real patient data that someone will accidentally use test data without realizing it is test data.
In the STU3 release, FHIR includes building blocks and principles for creating secure, privacy-oriented health IT systems; FHIR does not mandate a single technical approach to security and privacy.
In future releases, we anticipate including guidance on:
Maturity Level: 3 | Standards Status:Trial Use |
A security label is a concept attached to a resource or bundle that provides specific security metadata about the information it is fixed to. The Access Control decision engine uses the security label together with any provenance resources associated with the resource and other metadata (e.g. the resource type, resource contents, etc.) to
Security Labels enable more data to flow as they enable policy fragments to accompany the resource data.
The intent of a security label is that the recipient of resources or bundles with security-tags is obligated to enforce the handling caveats of the tags and carry the security labels forward as appropriate.
Security labels are only a device to connect specific resources, bundles, or operations to a wider security framework; a full set of policy and consent statements and their consequent obligations is needed to give the labels meaning. As a consequence of this, security labels are most effective in fully trusted environments - that is, where all trading partners have agreed to abide by them in a Mutual Trust Framework. Note also that security labels support policy, and specific tagging of individual resources is not always required to implement policy correctly.
In the absence of this kind of pre-agreement, Security Labels may still be used by individual parties to assist with security role checking, but they might not all be recognized and enforced, which in turn limits what information is allowed to flow.
Local agreements and implementation profiles for the use security labels should describe how the security labels connect to the relevant consent and policy statements, and in particular:
This specification defines a basic set of labels for the most common use cases trading partners, and also a wider array of security labels that allow much finer grained management of the information.
A security label is represented as a Coding, with the following important properties:
system | The coding scheme from which label is taken (see code system URI, and below) |
code | a code from the coding scheme that identifies the security label and code is a value from the code system |
display | The display form for the code (mostly for use when a system doesn't recognize the code) |
An example XML Patient Resource with a "Restricted" tag associated with it, as represented in an HTTP response:
<Patient xmlns="http://hl7.org/fhir"> <meta> <security> <system value="http://terminology.hl7.org/CodeSystem/v3-Confidentiality"/> <code value="R"/> <display value="Restricted"/> </security> </meta> ... [snip] ... </Patient>
A JSON search result that includes a resource that the receiving application must delete all copies of the resource after using it:
{ "resourceType" : "Bundle", "type" : "searchset", ... other headers etc..... "entry" : [ ... other entries .... { "resource": { "id" : "1", "meta" : { "security" : [{ "system" : "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code" : "DELAU", "display" : "delete after use" }] } ... other content etc..... } }, ... other entries .... ] }
Note: the actual terms used in these examples are described below.
The basic framework for security labels is described by the HL7 Healthcare Classification System. This specification identifies how security labels are defined and provides a relatively comprehensive list of labels. All of the HCS defined labels (see below for the lists) can be used as security labels on FHIR resources and bundles (e.g. requests and responses).
In addition, other security labels not defined here or in the HCS can be defined by jurisdictions, vendors and/or projects and used as appropriate. However, note that:
Note: The use of security labels and the expression of common shared security policies is a matter of ongoing discussion and development in several communities at this time.
This specification defines a set of core security labels for all FHIR systems. All conformant FHIR Applications SHOULD use these labels where appropriate. For all of these labels, how they are operationalized - their use and interpretation - is subject to the applicable Mutual Trust Framework agreement as described above.
Name/ Tag | Description |
Context of Use | |
Purpose Of Use |
These Purpose Of Use (system = http://terminology.hl7.org/CodeSystem/v3-PurposeOfUse) is an indication of a reason for performing one or more operations on information.
which may be permitted by source system's security policy in accordance with one or more privacy policies and consent directives.
Such as collecting personal health information for research or public health purposes.
Notes may be used as:
|
Data Sensitivity | |
Confidentiality codes |
These confidentiality class (system = http://terminology.hl7.org/CodeSystem/v3-Confidentiality) can be applied to any resource or bundle. They are generally assigned by the author of the resource
but can be modified subsequently as a matter of operational management. The Confidentiality classifications describe the sensitivity of the information in a resource with regard to
whether it should made available or disclosed to unauthorized individuals, entities, or processes. Notes:
|
Control of Flow | |
Delete After Use: ActCode.DELAU |
An application receiving a resource with this label must delete all copies after the immediate use for which the data was exchanged, is complete. Notes:
|
Do Not Re-use: ActCode.NOREUSE |
An application receiving a resource with this label may only use it for the immediate purpose of use. In particular, the application is not authorized to re-distribute (i.e. exchange this resource with any other application). Notes:
|
Test Data: ActCode.HTEST |
This marks that a resource has been created to test an application, and is not real production data Notes:
|
There is a special security label to support the commonly encountered "break-the-glass" protocol, where a clinician (usually in an emergency context) requests emergency unauthorized access to the patient's record.
Break the Glass | http://hl7.org/fhir/security-label#break-the-glass | The requester is asking for emergency access for patient treatment. Typically, this means that the patient is unconscious and not able to provide relevant information or consent. |
This purpose of use label is represented as a security label on the request, rather than on a resource, and so is represented in the request as a web category:
HTTP/1.1 GET fhir/Patient/482735/condition Content-Type: text/xml Access-Control-Allow-Origin: * Last-Modified: Thu, 19 Nov 2013 07:07:32 +1100 ETag: 24 Category: http://terminology.hl7.org/CodeSystem/v3-ActReason#BTG; scheme="http://hl7.org/fhir/tag/security"; label="break the glass"
While the principle of break-the-glass is well understood, implementing it well has some challenges. This specification defines a method to represent break-the-glass in an HTTP request, but does not define any policy or protocol around such requests. At a minimum, implementations must ensure:
See this paper for discussion of the issues involved in break-the-glass operations.
The security labels described above are a subset of the full set of security labels defined by the HL7 Healthcare Privacy and Security Classification System. The HCS defines 5 categories of security labels that may be applied to a resource:
Security Label | Card. | Values | Description |
Confidentiality Classification | 0..1 | ConfidentialityClassification | Security label metadata classifying an IT
resource (clinical fact, data, information
object, service, or system capability)
according to its level of sensitivity, which is
based on an analysis of applicable privacy
policies and the risk of financial,
reputational, or other harm to an individual
or entity that could result if made available
or disclosed to unauthorized individuals,
entities, or processes.
Example Uses: Unrestricted, Normal, Very restricted |
Sensitivity Category | 0..* | InformationSensitivityPolicy | Security label metadata that "segments" an
IT resource by categorizing the value,
importance, and vulnerability of an IT
resource perceived as undesirable to share.
Example Uses: STDs, Psychiatric care, Celebrity status |
Compartment Category | 0..* | Compartment | Security label metadata that "segments" an
IT resource by indicating that access and
use is restricted to members of a defined
community or project
Note: this is a different use of "Compartment" to the Patient Compartment use. Example Uses: Research, HR records |
Integrity Category | 0..* | SecurityIntegrityObservationValue | Security label metadata that "segments" an
IT resource by conveying the completeness,
veracity, reliability, trustworthiness, and
provenance of an IT resource
Example Uses: Anonymized, signed, patient reported |
Handling Caveat | 0..* | SecurityControlObservationValue | Security label metadata conveying dissemination
controls and information handling instructions
such as obligations and retention policies to which an
IT resource custodian or receiver must comply. This type of handling caveat SHALL be assigned to a clinical fact if required by jurisdictional or organizational policy, which may be triggered by a patient consent directive Example Uses: do not disclose, various restrictions on use, and policy marks |
Each of these security labels identifies a ValueSet that lists a set of possible codes for the security label.
The HL7 Healthcare Classification System also allows for Realm-specific privacy law or policy category codes for use in security labels in particular domains. These domains are included with this specification:
Security Label | Card. | Values | Description |
US Privacy Law | 0..* | ActUSPrivacyLaw | Security label metadata that "segments" an IT resource by indicating the legal provisions to which the assignment of a Confidentiality Classification complies in the US. |
Maturity Level: 4 | Standards Status:Trial Use |
Fast Healthcare Interoperability Resources (FHIR) is not a security protocol, nor does it define any security related functionality. However, FHIR does define exchange protocols and content models that need to be used with various security protocols defined elsewhere. This section gathers all information about security in one section. A summary:
Time critical concerns regarding security flaws in the FHIR specification should be addressed to the FHIR email list for prompt consideration.
A production FHIR system will need some kind of security sub-system that administers users, user authentication, and user authorization. Where this subsystem fits into the deployment architecture is a matter for system design:
![]() |
|
In this diagram, the red lines represent FHIR interfaces. From the perspective of the FHIR API, the client (consumer of FHIR services) may either interact with a security system that manifests as a FHIR server, and which depends on a subsequent FHIR interface to provide the actual storage, or either the client or server interacts with the security system independently. In each of these 3 scenarios, the different components may be assembled into applications or network components differently, but the same logical layout applies. The FHIR specification assumes that a security system exists, and that it may be deployed in front of or behind the FHIR API.
The security system includes the following subsystems:
Because there are a plethora of standards relating to the administration and functionality of the security system, FHIR does not provide user, profile, or other such administration resources. Instead, the FHIR resources are the targets of the policies expressed in these other approaches. What FHIR does specify is a way to apply security labels to resources so that a security system may use these (along with the contents of the resources if appropriate) to determine whether a user is authorized to perform a particular FHIR operation or not.
The appropriate protections for Privacy and Security are specific to the risks to Privacy and the risks to Security of that data being protected. This concept of appropriate protections is a very specific thing to the actual data. Any declaration of 'required' or 'optional' requirements that could be mentioned here are only recommendations for that kind of Resource in general for the most common use of that Resource. Where one uses the Resource in a way that is different than this most common use, one will have different risks and thus need different protections.
Most Resources will need some form of Access Control to Create, Update, or Delete. The following general guidance is given only as general guidance for READ and QUERY access:
These resources tend to not contain any individual data, or business sensitive data. Most often these Resources will be available for anonymous access, meaning there is no access control based on the user or system requesting. However these Resources do tend to contain important information that must be authenticated back to the source publishing them, and protected from integrity failures in communication. For this reason server authenticated https (TLS) is recommended to provide authentication of the server and integrity protection in transit. This is normal web-server use of https.
These Resources tend to not contain any individual data, but do have data that describe business or service sensitive data. The use of the term Business is not intended to only mean an incorporated business, but rather the more broad concept of an organization, location, or other group that is not identifable as individuals. Often these resources will require some for of client authentication to assure that only authorized access is given. The client access control may be to individuals, or may be to system identity. For this purpose possible client authentication methods such as: mutual-authenticated-TLS, APIKey, App signed JWT, or App OAuth client-id JWT For example: a App that uses a Business protected Provider Directory to determine other business endpoint details.
These Resources do NOT contain Patient data, but do contain individual information about other participants. These other individuals are Practitioners, PractionerRole, CareTeam, or other users. These identities are needed to enable the practice of healthcare. These identities are identities under general privacy regulations, and thus must consider Privacy risk. Often access to these other identities are covered by business relationships. For this purpose access to these Resources will tend to be Role specific using methods such as RBAC or ABAC.
These Resources make up the bulk of FHIR and therefore are the most commonly understood. These Resources contain highly sesitive health information, or are closely linked to highly sensitive health information. These Resources will often use the security labels to differentiate various confidentiality levels within this broad group of Patient Sensitive data. Access to these Resources often requires a declared Purpose Of Use. Access to these Resources is often controlled by a Privacy Consent. See the section below on Authorization and Access Control.
Some Resources can be used for a wide scope of use-cases that span very sensitive to very non-sensitive. These Resources do not fall into any of the above classifications, as their sensitivity is highly variable. These Resources will need special handling. These Resources often contain metadata that describes the content in a way that can be used for Access Control decisions.
For the RESTful API, normal HTTP security rules apply. Please follow the HTTP specification Security Considerations section 9. The Service Base URL will specify whether TLS is required. Client authentication may be required by the server, possibly including the requirement for client certificates. When returning responses to non-authorized clients, ensure that Hypertext Transfer Protocol (HTTP) headers of a web server and API error messages or faults do not disclose detailed information about the underlying web server that could be the source of potential exploitation.
Please follow IETF Best Current Practice (BCP 195) - "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Layer Security (DTLS)". This recommends TLS 1.2 or higher be used for all production data exchange, limits support for lower versions of TLS, and forbids SSL. Versions of TLS prior to TLS 1.2 should be used only where TLS 1.2 or higher is not available between partners. When using TLS, use with strong cipher suites (e.g. AES).
Consider using additional methods of security for an API to help authenticate where Domain Name System (DNS) responses are coming from and ensure that they are valid. For example, the use of Domain Name System Security Extensions (DNSSEC), a suite of extensions that add security to the DNS protocol, can ensure that domains associated with API endpoints that transmit health information or information required for API access are secure. DNSSEC provides origin authority, data integrity, and authenticated denial of existence. With DNSSEC, the DNS protocol is much less susceptible to certain types of attacks, particularly DNS spoofing attacks.
The TLS communications are established prior to any HTTP command/response, so the whole FHIR interaction is protected by the TLS communications. The security of the endpoints of the TLS communications must be risk-managed, so as to prevent inappropriate risks (e.g. audit logging of the GET parameters into an unprotected audit log).
When it is desireable to support browser-based javascript client applications, servers SHOULD consider enabling cross-origin resource sharing (CORS) for the REST operations. Consider advice from sources includeing Enable-CORS and Moesif blog on Guide to CORS Pitfalls. Experience shows that this is an area where ongoing issues may be expected as security holes are found and closed on an ongoing basis.
Other than testing systems, FHIR servers should authenticate the clients. The server may choose to authenticate the client system and trust it, or to authenticate the individual user by a variety of techniques. For web-centric environments it is recommended to use OpenID Connect (or other suitable authentication protocol) to verify identity of the end user, where it is necessary that end-users be identified to the application. It is recommended that OAuth be used to authenticate and/or authorize the client and user. The Smart-On-FHIR profile on OAuth is a recommended method for using OAuth.
The HEART Working Group has developed a set of privacy and security specifications that enable an individual to control the authorization of access to RESTful health-related data sharing APIs, and to facilitate the development of interoperable implementations of these specifications by others. IHE IUA Profile constrains OAuth token attributes to support Healthcare.
All systems are shall protect authenticator mechanisms, and select the type of credential/strength of authenticator based on use-case and risk management.
Correctly identifying people, devices, locations and organizations is one of the foundations that any security system is built on. Most applications of security protocols, whether authentication, access control, digital signatures, etc. rely on the correct mapping between the relevant resources and the underlying systems. Note that this isn't necessary. There is nothing in FHIR that requires or relies on any security being in place, or any particular implementation. However, real world usage will generally require this.
A holder of data should not allow the data to be communicated unless there are sufficient assurances that the other party is authorized to receive it. This is true for a client creating a resource through a PUT/POST, as much as it is true for a server returning resources on a GET. The presumption is that without proper authorization, to the satisfaction of the data holder, the data does not get communicated.
Two of the classic Access Control models are: Role-Based Access Control (RBAC), and Attribute-Based Access Control (ABAC).
In Role-Based Access Control (RBAC), permissions are operations on an object that a user wishes to access. Permissions are grouped into roles. A role characterizes the functions a user is allowed to perform. Roles are assigned to users. If the user’s role has the appropriate permissions to access an object, then that user is granted access to the object. FHIR readily enables RBAC, as FHIR Resources are object types and the CRUDE (Create, Read, Update, Delete, Execute) events (the FHIR equivalent to permissions in the RBAC scheme) are operations on those objects.
In Attribute-Based Access Control (ABAC), a user requests to perform operations on objects. That user's access request is granted or denied based on a set of access control policies that are specified in terms of attributes and conditions. FHIR readily enables ABAC, as instances of a Resource in FHIR (again, Resources are object types) can have attributes associated with them. These attributes include security tags, environment conditions, and a host of user and object characteristics, which are the same attributes as those used in ABAC. Attributes help define the access control policies that determine the operations a user may perform on a Resource (in FHIR) or object (in ABAC). For example, a tag (or attribute) may specify that the identified Resource (object) is not to be further disclosed without explicit consent from the patient.
The rules behind the access control decision are often very complex, and potentially depend on information sourced from:
For one source of further information, see the IHE Access Control white paper
Access control constraints may result in data returned in a read or search being redacted or otherwise restricted. See Variations between Submitted data and Retrieved data.
A web-server, especially hosting FHIR, must choose the response carefully when an Access Denied condition exists. Returning too much information may expose details that should not be communicated. The Access Denied condition might be because of missing but required Authentication, the user is not authorized to access the endpoint, the user is not authorized to access specific data, or other policy reasons.
To balance usability of the returned result vs appropriate protection, the actual result method used needs to be controlled by policy and context. Typical methods of handling Access Denied used are:
Return a Success with Bundle containing zero results – This result is indistinguishable from the case where no data is known. When consistently returned on Access Denied, this will not expose which patients exist, or what data might be blinded. This method is also consistent with cases where some results are authorized while other results are blinded. This can only be used when returning a Bundle is a valid result.
Return a 404 “Not Found” – This also protects from data leakage as it is indistinguishable from a query against a resource that doesn’t exist. It does however leak that the user authentication is validated.
Return a 403 “Forbidden” – This communicates that the reason for the failure is an Authorization failure. It should only be used when the client and/or user is well enough known to be given this information. Thus this method is most used when the user is allowed to know that they are forbidden access. It doesn’t explain how the user might change things to become authorized.
Return a 401 “Unauthorized” – This communicates that user authentication was attempted and failed to be authenticated.
Note that if a server allows PUT to a new location, it is not feasible to return 404 Not Found. This means that clients can use this to test whether content exists that they are not able to access, which is a minor, but potentially significant, leak of information.
FHIR provides an AuditEvent resource suitable for use by FHIR clients and servers to record when a security or privacy relevant event has occurred. This form of audit logging records as much detail as reasonable at the time the event happened.
When used to record security and privacy relevant events, the AuditEvent can then be used by properly authorized applications to support audit reporting, alerting, filtering, and forwarding. This model has been developed and used in healthcare for a decade as IHE-ATNA profile. ATNA log events can be automatically converted to AuditEvent resources, and from there, client applications are able to search the audit events, or subscribe to them.
With regard to HTTP logs, implementers need to consider the implications of distributing access to the logs. HTTP logs, including those that only contain the URL itself, should be regarded as being as sensitive as the resources themselves. Even if direct PHI is kept out of the logs by careful avoidance of search parameters (e.g. by using POST), the logs will still contain a rich set of information about the clinical records.
Several FHIR resources include attachments. Attachments can either be references to content found elsewhere or included inline encoded in base64. Attachments represent security risks in a way that FHIR resources do not, since some attachments contain executable code. Implementers should always use caution when handling resources.
See Security Labels.
FHIR resources include an XHTML narrative, so that applications can display the contents of the resource to users without having to fully and correctly process the data in the resource. However, displaying HTML is associated with several known security issues that have been observed in production systems in other contexts (e.g. with CDA). For this reason, the FHIR narrative is not allowed to contain active content. However, care is still needed when displaying the narrative:
Also note that the inclusion of an external reference to an image can allow the server that hosts the image to track when the resource is displayed. This may be a feature or a problem depending on the context.
In addition to narrative, Documents may also contain stylesheets. Unlike with CDA, the stylesheets are simple CSS stylesheets, not executable XSLT, so the same security risks do not apply. However CSS stylesheets may still reference external content (e.g. background images), and applications displaying documents should ensure that CSS links are not automatically followed without checking their safety first, and that session/identifying information does not leak with any use of external links.
Maturity Level: 2 | Standards Status:Trial Use |
Though FHIR resources are primarily designed for the RESTful HTTP-based implementation, it is not necessary to use a RESTful interface when exchanging the resources; one way that they can be exchanged is in the context of services. Service Oriented Architecture (SOA) is an architecture pattern using services to encapsulate and provide discrete pieces of application functionality to each other. Services communicate by invoking public interfaces and exchanging information (as parameters and outputs) in accordance with a well-defined service contract.
Generally speaking, services are cohesive sets of functions that maintain responsibility for both data and "state" for the scope of their responsibility. Services have a unity of function, such as Terminology Management, Identity Management, or so on, working with other services in collaboration as part of an orchestrated workflow. Data within a service typically follows a "black box" model and is not classically exposed, instead using pre-defined interfaces to make specific behavioral requests for the service to fill.
To relate this to FHIR, resources in a service-oriented implementation can serve two discrete roles: either as a payload parameter, specifying information flowing into or out of a service; or in a behavioral sense, using FHIR APIs as the invocation mechanism for engaging a service. Service APIs are often realized using either RESTful or SOAP-based interfaces.
Of note, there are potential benefits in considering usage of FHIR and SOA together. FHIR allows for ease of implementation and ready access to data payload in an open way. SOA has maturity around transactional integrity across distributed systems instances, providing a framework for loose-coupling and addressing pre-conditions, exception handling, and other implementation considerations of complex distributed systems.
This section illustrates different contexts to allow implementers to make informed decisions at implementation time, considering potential impacts and solution patterns to benefit specific situations. In doing so, this section will clarify what is meant to apply SOA principles and specifications within a FHIR environment/implementation, and the converse. It will identify the situational factors to consider, and the elements of the SOA discipline that can be applied for more effective FHIR implementation, providing a roadmap on how to optimize your implementation toolkit to make you and your team most effective.
This section is being included as FHIR offers a highly flexible framework for interoperability that can be deployed that can be used in a variety of different ways, and in ways that have the potential to hinder interoperability if not done thoughtfully or consistently. Use of SOA patterns and approaches can mitigate this risk, limiting the potential liability resulting from the extreme flexibility of FHIR and fostering an overall framework that leads to deployment and consistency. SOA provides guidance for how components interact, how to partition responsibilities, and how to manage workflows among different parts of systems, all of which have potential utility in FHIR implementation settings.
Generally, the definition of particular services is a domain or context specific task, and it is anticipated that this would be done as separate specifications that make use of the underlying facilities defined in this specification. HL7 has already defined a portfolio of services that take advantage of REST- and SOAP-based interfaces, but the parameters passed to and from those services are not at present resource-based. These are potential extension points that may lend well for FHIR implementation. Services defined like this are able to build on the common underlying platform features defined in this specification such as REST or messaging, and add specific interactions where appropriate. Alternatively, the service interfaces can build an entirely separate implementation.
Note that for each of the items below, there are paired sets of standards, an HL7 Standard defining the functional specification, and an OMG Technical Standard containing SOAP bindings (for all of the items below) and REST bindings (for about half of the items below).
The portfolio of healthcare SOA service specifications includes:
Note: FHIR-enablement of the services above is already occurring on a limited basis. The Clinical Quality Improvement Framework (CQIF) portion of the FHIR specification is an example of a technical interface and resources that have been influenced by prior SOA work. Similarly, this specification defines a Terminology Service which is tightly integrated with the RESTful API (note: this terminology service has different goals than the CTS2 service, so they are not functionally equivalent). FHIR itself is a framework for the instantiation of an RLUS service. Definition of other additional services based on the service interface definitions provided by the HL7 SOA work group will be considered if there is sufficient interest in this.
Given that there are a set of available services that can be applied directly or used as a pattern in conjunction with FHIR, it merits consideration that there are alternative ways to bring together FHIR and SOA, each of which has benefits and drawbacks. Three specific styles of implementation have been identified:
Determining which of the above implementation styles is best suited to a particular situation is context-dependent. The following table presents these alternatives, deliberately using qualitative measures to help navigate to the best-fit based upon influencing factors. "Harvey Balls" in the table below indicate relative strengths and weaknesses of the implementation alternatives.
Solution Quality | Short Description | #1:FHIR + REST (RESTful FHIR) | #2 FHIR + WS* | #3 FHIR + SOA Pattern | Comments |
Support of transactional integrity | Transactions may involve multiple steps composed together into a single unit | ◒ | ◒ | ● | Transactional integrity is not assured in #1 or #2 but can be hand-coded. #3 assures that this is addressed |
Support of stateless transactions | Transactions are independent and do not require supporting context | ● | ● | ● | Each of the implementation approaches are capable of supporting stateless processing |
Support of "loose coupling" | Minimum of dependencies between the calling and responding system; reduces burden on client to manage context of interaction with service | ◒ | ◒ | ● | The notion of "loose coupling" is fundamental to SOA and inherent in that architecture. Loose coupling can be supported by FHIR, but it does not innately do so |
Use of FHIR Resources as Data Payload | Representation of FHIR resources for use as query or return parameters | ● | ● | ● | Data payload includes input data as well as data returned |
Support of Dynamic Service Discovery | Provides for service registration, search, discovery, and late binding | ◒ | ◒ | ● | This is part of SOA specification and customary in implementations. For the others, it is up to the approach |
Provides resource-oriented operations | Supports ability to create, read, update, delete resources; | ● | ◒ | ◒ | Direct access to resources/data revisions in a strength of REST and FHIR. Direct access to fine-grained transactional operations are generally not supported within SOA |
Suitability for atomic transactions | Fitness to support fine-grained transactions, such as data access or targeted update | ● | ◒ | ◒ | REST is ideally suited for point access or updates of specific data elements/resources - functions discouraged within SOA and WS* |
Suitability for composite transactions | Fitness to support complex transactions: context-sensitivity, multi-step workflows, etc. | ◒ | ● | ● | SOA provides for complex event processing, multi-step sequencing, orchestration |
FHIR resources are designed to be used in a wide variety of contexts. In particular, FHIR resources are required to be suitable for use in a REST environment. This means that there are number of design requirements and choices that impact how suitable resources are for use with services.
If service use was the only consideration, different decisions would be made, and resources would be more suitable for use with services. However, this would curtail their usefulness and reusability in other contexts.
API/Interface Design. Services' API design is explicit and exposes service capabilities which are a part of a service contract to consuming applications. This contrasts with what is the default interface into a FHIR server of a REST-based interface exposing CRUD operations and stateless access. Good SOA design practice indicates loosely-coupled access (e.g., external clients do not have visibility into the inner workings of a service) improves implementation flexibility over time, permitting design and performance improvements with the maturation of the implementation. As such, interfaces are typically exposed and aligned with business functionality (such as "Register Patient" or "Validate Identity").
Bridging what is not necessarily a natural-fit between SOA operations and RESTful operations are key to interface design. Implementers may elect to apply finer grained FHIR interactions to be encapsulated in coarse-grained functions, delegating those responsibilities to either implementations within a FHIR instance or to external code not visible to the service consumer.
Principal within the design objective is to minimize or eliminate responsibilities on behalf of the service consumer to understand or apply knowledge of the service implementation. This frees up the service provider to be able to evolve and improve the inner workings of the service without a "ripple effect" adversely impacting service consumers. In doing so, technical dependencies are minimized. Several good sources of SOA Design Patterns are available from HL7 and other public sources.
Data Storage and Coherence. The approach to and complexities associated with data storage and overall data coherence will significantly depend upon whether an implementation is subject to enterprise policies and whether data consistency is the responsibility of the service provider or consumer. In Enterprise settings, these issues are typically governed by organizational policy. FHIR servers and their data persistence would need to fit within that policy, with data access being in compliance with that policy and services interacting with "policy enforcement points" to assure that appropriate permissions are in place.
Where data consistency is the responsibility of the service (or server) use of SOA-friendly interface protocols, such as SOAP and potentially REST, create the access channel for integration. This may necessitate defining minimum sets of data that are required to comply with data coherence expectations (in other words, a service contract that specifies the collection of resources that must be updated in tandem, and the scope of what constitutes a ‘single transaction’ - more on this in the Transactional Integrity section).
In alternative implementations data storage is managed within the FHIR server, consistent with non-SOA FHIR implementations. Data consistency is the responsibility of the Server but responsibility may carry to consuming applications (if they are provided with sufficient update rights so as to make that a concern). Data validation also has a shared responsibility, first with the FHIR Server, and additionally with the authorized updating applications. Data visibility is a product of the REST interface, typically allowing CRUD operations to the data element level.
Transactional Integrity. When encapsulating functionality within a SOA-type service, data and transactional integrity are essential in making sure that data received and stored is accurate and consistent with what was received. An issue particularly with update functions, the ability to update multiple different resources and maintain harmony among them as part of a broader transaction is how this is typically realized.
Should one part of the update ‘fail’, one would expect all of the other updates to be "rolled back" to a prior, stable state. Rollback is not expressly specified as part of the FHIR. Data update and integrity becomes the responsibility of each service. The FHIR specification does not inherently provide for concurrency management (e.g., managing of "deadlock" conditions where two resources each await update permission from the other). As a result, within the FHIR server itself it is assumed that fault tolerance and server availability is being managed (beyond the scope of the specification).
Applied use of SOA patterns have benefits in terms of distributed transactional integrity, as SOA has substantially removed burdens from calling (client) applications, instead levying these responsibilities upon the service provider. This has relevance because it is customary in larger scale implementations (such as large enterprises) that service consumers are varied and not necessarily know in advance to the service. As a result, these implementation patterns make for more robust infrastructure, mitigating potential implementation risk and ultimately improving data quality. We note that these elements can be manually accommodated in FHIR implementations, absent use of SOA patterns, though that can lead to inconsistent interpretation, delegated responsibility to client application(s), and the potential for incompatible implementations.
Modularity. The modularity of resources - which resources are defined, and why - is driven by a wide set of considerations around how they are used. Resources are a platform on which a set of business/clinical services of various kinds are provided. Accordingly, the resources are defined for general use, and they can be expected to be less suitable for a particular service than custom defined structures. The pay back is wider re-use of the information that the service deals with.
Effective "service-orientation" establishes modularity at both a macro and micro-level. At the macro-level, services themselves are modular, componentized, and composable. Since each service has a singularity of purpose with a well-defined interface, they are naturally suited to working in tandem with other services and consistent with modular design. At a more fine-grained level, the interfaces into and out of services also allow for modularity, and the ability to leverage the structure of FHIR resources as a payload descriptor for carrying data structures and corresponding semantics across APIs is modularly based.
Explicit State. All resources represent the various states of the record and real world entities involved in a transaction explicitly. This is necessary for use in RESTful and document contexts, where there is no explicit transaction. Service interactions are typically associated with implicit semantics, such as a request to change the status of a particular resource to something else, for example. The fact that resources that carry this state explicitly as well as the transaction fixing state implicitly creates duplication between the two, and this will need to be managed.
Error Handling. SOA provides an implementation approach providing consistency in error handling, escalation, and error management. These tools can be leveraged to identify likely error conditions and exceptions based upon prior SOA work, helping to put into place infrastructure within FHIR to manage those exceptions. Moreover, this alignment creates future opportunity to more effectively integrate FHIR resources into an enterprise SOA fabric should that become a need. It is not anticipated that there is a need to change error management for FHIR, except to address payload-specific errors that may arise.
The FHIR specification does not specifically address error handling between and across servers and clients. When implementing within larger or more complex environments, particularly in situations where multiple FHIR servers may be involved (especially if they are provided by different vendors/implementations), error handing and management can quickly become complex and untenable.
Resource References. The most obvious impact is that resources refer to each other using full URL based references, and there are a number of rules around how these references are resolved. In the context of a service, this means that the references between modules carry this extra weight of choice and obligation, even when it might not be necessary.
FHIR resources or bundles may be used as the parameters or outputs of service interfaces.
Orchestration. Orchestration is a term typically used within SOA to describe the steps, sequencing, and dynamic adjustment of workflow to meet a process need. Orchestrations may be entirely automated and fulfilled in a short timeline, or longer and multistep in fulfillment of a business process that may involve manual steps and human intervention. In the context of FHIR implementation, orchestration would refer to the sequencing of collections of FHIR (or service) calls that are used in tandem to fulfil a specific need.
Orchestration is neither natively supported nor unsupported in FHIR, save the availability of the FHIR Batch mode which allows for some degree of compounding of operations. In a SOA environment, orchestration is typically realized by documenting in some formalism, such as Business Process Modeling Notation (BPMN), a sequence of steps and flows, and inherent logic or decision-points affecting that flow. An engine is then capable of executing the process flow, receiving inputs during execution to adjust or adapt those processes based upon situational need as part of delivery fulfillment.
There are many examples where this approach is advantageous. For example, in a Care Management situation, test results, current problems, chief complaint, and potentially even resource availability might affect subsequent steps in fulfilling a care plan. Based upon changes to any of these factors, the sequence of calls and ultimately the systems or FHIR servers involved would vary. The role of automated clinical decision support is another example that naturally ties to workflow orchestration, adjusting care pathways based upon patient evaluation and affecting process flows within a health system.
At present, to support this complexity within a FHIR setting without the use of SOA tools, these flows would need to be manually coded, either by having a directed sequence of calls, or by creating an independent capability effectively acting as an orchestrator. This can be supported within FHIR exclusively, but all of the steps and corresponding state management would need to be done by hand. FHIR Batch provides some of this capability, allowing for aggregation of multiple steps, but does not necessarily support the event processing needed in complex.
Security. Security is inherently a dimension of any enterprise SOA architecture, meaning that the responsibility within a service implementation is to provide the "hooks" to interact with that architecture. In other words, the service does not need to create or enforce security, it needs to interact with those enterprise components that have that responsibility. This includes topics such as identity management, access control, or other dimensions of a secure solution. SOA guidance can foster an effective design involving FHIR in support of authentication, policy enforcement, role-based access controls, and a host of other provisions and protections. It is important to note that within SOA, security is an established, mainstream, and mature offering. Reuse of these concepts can help prevent inadequate, incomplete, or ineffective security measures within FHIR, and eliminate the need to re-invent solutions exclusively for FHIR.
Enterprises typically have security architecture into which a SOA environment will have already integrated. Service implementations would rely upon this existing infrastructure as part of authentication, access control, etc. Policy enforcement is a function of the architecture and not a specific service itself. Services would rely upon policy enforcement points to govern access to information.
While technical dimensions of security would be addressed by the security architecture directly, FHIR implementers should anticipate that data-specific access control policies would need to be captured and formalized so that they are enforceable within the architecture. For example, if a new service is handling protected health information, the policy enforcement point within the architecture would need to know that the service has that nature of data.
Resource Identity. All resources have a single identity (the full URL), and a logical id which may be maintained as the resource moves from server to server (see Managing Resource Identity for further discussion). Since this identity is used by any reference to the resource, it must be maintained when the resource is exchanged so that references from other resources to the one being exchanged can still be resolved. Any use of resources in a service environment needs to address how these references can be resolved. This can be achieved by delegating the reference resolution to a RESTful framework, by ensuring that all the relevant resources are contained in the service call, or by making some service-based arrangement by which additional resources can be retrieved. Services that exchange resources SHOULD maintain resource identity. Further, as explicit version tracking is not a guaranteed capability of a service call, services that exchange resources should include version information associated with resources being exchanged.
Capability Statement. When using RESTful exchange, messaging, and document based exchange, the Capability statement allows authoring and reading applications to describe how they use a resource. The Capability Statement supports trading partner negotiation from specification time through to run-time discovery. The Capability statement doesn't provide any equivalent way to make declarations about services, though this might be added in the future if common requirements emerge. Services are expected to make appropriate arrangements around discovery and compatibility, though it is expected that these will vary considerably.
Services that exchange resources MAY choose to provide support for describing and changing descriptions of service implementations.
At its core, FHIR is based upon the elemental capabilities of Create, Read, Update, Delete (CRUD), allowing access to resources where interaction is primarily based upon these operations. Of note, multi-step or complex processing levies requirements upon the calling, client application. Sequencing of events, particularly when those events involve orchestration of complex or dynamic processes, can benefit from the application of SOA techniques and patterns. This is common where multi-step processing is involved, and particularly important when adjustments to a process flow can be made based upon situational context.
As these areas are both commonplace within health settings and not inherent strengths of FHIR, the marriage of FHIR and SOA techniques provides a viable and beneficial path forward to improving implementation and mitigating risks by leveraging proven and established industry best-practices.
SOA design patterns are frequently used to govern interactions for dynamic processes, non-sequential workflows, or dynamic workflows involving human intervention and/or consideration of external factors as part of processing. The ability to model interaction patterns using languages such as SOAml, and to define roles and role interactions, are tools that may be useful to FHIR development in these circumstances, and would be indicators signaling that SOA has the potential to add value to a FHIR implementation.
SOA design principles can provide guidance to a FHIR implementer resulting in reduction of co-dependencies between components, promoting "loose coupling" and minimizing potential impacts resulting from changes to inner workings of one component adversely affecting others. (For those familiar with the term, this encourages "black box" implementation).
SOA provides guidance around data persistence, durability, and expectations in support of the data lifecycle.
FHIR has proven itself as beneficial in that it provides an easy-to-implement and coherent approach to accessing healthcare resources using a modern protocol stack. SOA has proven itself over time in multiple vertical market segments as a way to divide responsibilities and authoritatively manage information across distributed systems. Marrying the discipline of SOA with the implementation ease of FHIR is a winning combination when the situation warrants. Implementers should consider evaluation of the contextual landscape to determine where FHIR and SOA have the opportunity to benefit from complementary implementation leverage points.
Recognizing that there are situations where the coming-together of FHIR implementation and SOA techniques are advantageous, there are several implementation approaches available. Note that the selection of which approach is advantageous for any given situation will depend upon a variety of factors: existing legacy implementation and available APIs (particularly for interfacing applications), the strategic direction/IT roadmap of the organization, and so on. Noting that there are different styles of realizing FHIR and SOA together, a recap of the principal alternatives would include:
It is important to note that electing to apply SOA patterns to FHIR implementation does not fundamentally change the nature of what is being implemented. Applied correctly, it results in minor adaptation to coding and interface design resulting in enhanced consistency across implementations as well as enhanced interoperability and robustness.
These considerations are summarized in this table:
Capability | #1:FHIR + REST (RESTful FHIR) | #2 FHIR + WS* | #3 FHIR + SOA Pattern | Comments |
Supports dynamic adjustment in workflows | ○ | ◒ | ● | In a native FHIR environment, this must be done by hand. The WS* stack provides for some interaction patterns, but limited. Use of formal notation (BPMN) and service orchestration is most robust option |
Supports ability to batch multiple operations | ◒ | ◒ | ● | FHIR Batch allows for concatenation of multiple process steps. SOA Orchestration allows for fine grained control, grouping and sequencing of multiple operations |
Provides for management of data coherence (e.g. Deadlocks, transactions) | ○ | ○ | ● | SOA principles define data governance, assigning responsibility for all data management within a service contract |
Provide support for orchestration languages (BPMN, SOAml) | ○ | ◒ | ● | SOA applies a systematic framework for orchestration using industry accepted formalisms, avoiding costs and complexities associated with an ad-hoc approach |
SOA in a FHIR Environment considers the benefits of applying SOA patterns and best-practices to a FHIR implementation community. In these cases, developers are faced with implementation decisions that have the potential to benefit from existing case studies, design patterns, or guidance that may either help provide consistency among FHIR implementations, or which may address gaps - either known or unidentified - resulting from implicit assumptions around a FHIR implementation.
FHIR in a SOA Environment considers the implications of using FHIR in a large, established enterprise that has or is making investments in SOA infrastructure. In these cases, shared services, enterprise policies, and existing infrastructure is common, and FHIR implementations would need to fit within the fabric of that environment.
Finally, it merits mention that not every FHIR implementation benefits from SOA, and vice-versa. The goal of this section is to help implementers navigate based upon their specific considerations to help determine if and to what extent these approaches provide benefits.
Maturity Level: N/A | Standards Status:Trial Use |
This specification recommends the use of W3C Digital Signatures for signatures. Resources can be signed using the Provenance resource to carry a detached digital signature. The Signature datatype is available to support various signature types including non-repudiation purposes. Further details on creation and validation of Signatures are defined.
In addition, documents may be signed using an enveloped signature. A specification for enveloped signature is profiled in the IHE DSG profile.
Neither of these definitions prohibits the use of other ways of using digital signatures.
the use of signatures with RESTful interfaces is a poorly understood area, and we would welcome reports of implementation experience. See discussion on use of Digital Signature in FHIRFeedback is welcome here.
FHIR Infrastructure Work Group | Maturity Level: N/A | Standards Status: Informative |
This page summarizes the use of SNOMED CT in the base FHIR Specification. It is used by HL7 and IHTSDO to help with SNOMED CT licensing management.
In principle, this base FHIR Specification only uses concepts defined in the International distribution of SNOMED CT, while FHIR implementation guides that use SNOMED CT are generally published by HL7 Affiliates under agreements with National distribution centers. However, there are some US specific codes on this page; HL7 is working with IHTSDO towards remove these from the specification (hopefully they will be elevated to the international SNOMED CT distribution).
The following value sets reference SNOMED CT. The table lists the value sets, and then the places they are used from, and includes the binding strengths
The value sets that reference SNOMED CT explicitly reference the following SNOMED CT concepts. The table lists the concepts, and then the value sets and places they are used from, and includes the binding strengths. The table does not include codes published in the expansions.
Maturity Level: 5 | Standards Status:Trial Use |
Source | SNOMED CT is owned, maintained and distributed by SNOMED International. SNOMED International is the organization which publishes the International Edition of SNOMED CT. SNOMED International Members may also distribute their own SNOMED CT National Edition, which contains the international release plus local extension content and derivatives. |
System | The URI http://snomed.info/sct identifies the SNOMED CT code system. |
Version | Where a code system version is used, it should be specified as a URI that represents a specific SNOMED CT Edition published on a particular date (e.g. the International Edition or a National Edition, with a version date), following the SNOMED CT URI Specification (see note below). |
Code | The following SNOMED CT artifacts are valid in the code element for the http://snomed.info/sct namespace:
Concept IDs and
SNOMED CT Expressions (using SNOMED CT Compositional Grammar). SNOMED CT Terms and Description Identifiers are not valid as codes in FHIR, nor are other alternative identifiers associated with SNOMED CT Concepts.
Note: When SNOMED CT Terms must be exchanged, use the Description Id Extension. |
Display |
The correct display for a SNOMED CT
concept is one of the terms
associated with that concept. The best display is the preferred term in the
relevant language or dialect, as specified in the associated language
reference set. SNOMED CT synonyms may be case sensitive.
SNOMED International does not define terms for expressions. If a SNOMED terminology producer publishes human-readable terms for expressions in an expression repository, this term may be used as the display. Similarly, if a SNOMED terminology producer publishes an official template for generating terms from an expression, a term generated using the template may be used as the display. If no term or description template has been published, the full expression with terms embedded may be used. Note that Display is not intended to contain terms entered by the user that have not been officially published by a SNOMED CT Terminology Producer. |
Inactive | Inactive codes are identified using the 'inactive' property (see below) |
Subsumption | SNOMED CT Subsumption testing for concepts is based on the |is a| relationship defined by SNOMED CT |
Filter Properties | Several filter properties are defined, as described below |
This specification publishes a canonical SNOMED CT CodeSystem resource. See also the SNOMED CT Usage Summary.
Note: The SNOMED International glossary explains some of these SNOMED CT specific terms.
This specification includes content from SNOMED Clinical Terms® (SNOMED CT®) which is copyright of the International Health Terminology Standards Development Organisation (IHTSDO) (trading as SNOMED International). Implementers of these specifications must have the appropriate SNOMED CT Affiliate license - for more information contact http://www.snomed.org/snomed-ct/get-snomed-ct or info@snomed.org.
There is no single distribution that contains all defined SNOMED CT codes in all contexts of use. Instead the International Edition contains all concepts shared and agreed to be internationally relevant and each National Release Centre distributes this International Edition plus additional national content (to extend the international set). Other release authorities may also be designated. The SNOMED CT URI Specification describes how to unambiguously reference a particular version of a SNOMED CT edition:
http://snomed.info/sct/[sctid]/version/[YYYYMMDD]
where [sctid] is the concept id that identifies the given SNOMED CT edition (based on the identifier of the most dependent module), and "YYYYMMDD" is the date of release. Examples of sctids that identify a specific edition are listed here.
Note that many implementations are in the habit of simply using the date of release in the form YYYYMMDD (e.g. "20140531"), and assuming that the edition is known. However this is not always safe, so implementations that populate the version element SHOULD use the URI form.
Servers SHOULD regard provision of the date only for the version (without an sctid) as an error, and refuse to process the interaction or operation. At minimum the URI SHOULD contain the sctid of the SNOMED CT distribution:
http://snomed.info/sct/[sctid]
Implementers must note, if no version URI is provided when utilizing SNOMED CT, the Terminology Service may default to the most recent version of the SNOMED CT International Edition available on the service (or the latest available of another edition that may be preferred for the locale). Further, if the date of release is not provided, the Terminology Service may default to the most recent version of the named SNOMED CT distribution (e.g. 32506021000036107 for Australia).
In terms of the CodeSystem resource definitions, this means that SNOMED CT is distributed as a set of overlapping fragments that contain different parts of the entire code system that is SNOMED CT. Terminology servers and users always need to be aware of which fragment(s) are in use at any time, though implementations can sometimes safely assume that a national distribution is the only scope. Note that because of SNOMED CT's large size, there is no expectation that implementers will ever use a CodeSystem resource instead of the SNOMED CT RF2 format as a way to distribute SNOMED CT content.
In the ValueSet resource any number of terms ('designations') in additional languages and dialects can be specified for a particular concept in a value set definition using the ValueSet.compose.include.concept.designation element. The language is specified as a BCP-47 language code as required by the 'designation.language' element, with the value taken from the 'languageCode' field of the RF2 Descriptions file ('languageCode' is ISO-639-1, a subset of BCP-47). The type of the term (e.g., the SNOMED CT code for "Fully specified name", "Synonym" or "Definition") can be specified in 'designation.use'.
[Note that ValueSet.compose.include.concept is only used when the value set is defined extensionally (i.e. as an enumerated list of concepts). For intensionally defined value sets (i.e. using one or more filters) additional terms could be added using CodeSystem.concept.designation, as noted below.]
The CodeSystem resource can also similarly be used to specify additional terms ('designations') for a concept using the CodeSystem.concept.designation element (the additional terms may be from a published national or other localized SNOMED CT edition or provided in a code system supplement). If supported by the terminology server, the additional terms are available to be returned in a value set expansion (controlled by the $expand operation 'includeDesignations' input parameter).
A SNOMED CT Expression is a structured combination of one or more clinical concepts, stated using Compositional Grammar Syntax. Expressions may optionally contain display terms.
The SNOMED International URI specification uses the namespace http://snomed.info/sct for the code system, and the URI http://snomed.info/id for the individual concepts in the code system. This means that when a SNOMED CT concept is converted from the system::code pair, where the system is http://snomed.info/sct, to the RDF ontological form, the representation is http://snomed.info/id/[concept-id]. Expressions are represented using the URI pattern http://snomed.info/scg/[expression]. Expressions represented in this way SHALL NOT contain whitespace, terms or comments.
In addition to the standard properties, the following properties are defined for SNOMED CT:
Property Name | Data Type | Comments |
inactive | boolean | Whether the code is active or not (defaults to false). This is derived from the active column in the Concept file of the RF2 Distribution (by inverting the value). |
sufficientlyDefined | boolean | True if the description logic definition of the concept includes sufficient conditions. This is derived from the definitionStatusId value in the Concept file of the RF2 distribution (i.e. If 900000000000073002 |Sufficiently defined concept definition status| then true). |
moduleId | code | The SNOMED CT concept id of the module that the concept belongs to. |
normalForm | string | Generated Necessary Normal Form expression for the provided code or expression, with terms. |
normalFormTerse | string | Generated Necessary Normal form expression for the provided code or expression, concept ids only. |
SNOMED CT relationships, where the relationship type is subsumed by 410662002 |Concept model attribute|, also automatically become properties. Properties that represent SNOMED CT concept model attributes are referred to using their concept id, rather than their human readable term.
For example, the laterality property is represented using the concept id '272741003', rather than the term 'laterality':
Property Name | Data Type | Comments |
272741003 | code |
The value of the laterality attribute in the definition of the given code or expression. The equivalent URI for the laterality property is |
Note that when a $lookup operation is performed on a SNOMED CT concept,
servers SHALL return the URI for the edition and version being used (see above) in the version
property.
Other properties are at the discretion of the server and the client.
This section documents the property filters that can be used with the SNOMED CT code system in value set composition statements. For implementer convenience, some of the property filters are documented in terms of the SNOMED CT Expression Constraint Language, but this does not imply that its use is required.
Description | Select a set of concepts based on subsumption testing |
Property Name | concept |
Operations Allowed | is-a |
Values Allowed | [concept id] |
Comments | Includes all concept ids that have a transitive is-a relationship with the concept id provided as the value (including the concept itself) |
Example | Administration Methods |
SCT ECL | << [concept] (Long syntax: descendantOrSelfOf [concept]) |
Description | Select a set of concepts based on their membership of a SNOMED CT reference set |
Property Name | concept |
Operations Allowed | in |
Values Allowed | [concept id] |
Comments | Includes all concept ids that are active members of the reference set identified by the concept id provided as the value |
SCT ECL | ^ [concept] (Long syntax: memberOf [concept]) |
Description | Select a set of concepts based on a formal expression constraint |
Property Name | constraint |
Operations Allowed | = |
Values Allowed | [expression constraint] |
Comments |
The result of the filter is the result of executing the given SNOMED CT Expression Constraint.
Example: "compose": { "include": [ { "system": "http://snomed.info/sct", "filter": [ { "property": "constraint", "op": "=", "value": "<< 30506011000036107 |Australian product|: 700000101000036108 |hasTP| = 17311000168105 |Panadol|" } ] } ] } |
Description | Specify whether postcoordination is allowed or not |
Property Name | expressions |
Operations Allowed | = |
Values Allowed | true or false |
Comments | Expressions, if allowed, are subject to the same rules as precoordinated concepts. [Note: Simple reference sets do not include expressions.] |
Example | Administration Methods |
SCT ECL | n/a |
Implicit value sets are those whose specification can be predicted based on the grammar of the underlying code system, and the known structure of the URL that identifies them. SNOMED CT has two common sets of implicit value sets defined: By Subsumption, and By Reference Set. These implicit value sets do not use complex queries. Implicit value sets can also be defined using an expression constraint. The implicit value set capability allows a single URL to serve as a value set definition, and can serve as the basis for the $expand operation and for other value set references.
If any value set resources exist with an identifier that conforms to the URL patterns specified below, the content of the resource must conform to the template provided. Profiles and other value set references are allowed to reference these value sets directly (by reference as a URI, rather than by a literal value set reference).
A SNOMED CT implicit value set URL has two parts:
The URL http://snomed.info/sct should be understood to mean an unspecified edition/version. This defines an incomplete value set whose actual membership will depend on the particular edition used when it is expanded. If no version or edition is specified, the terminology service SHALL use the latest version available for its default edition (or the International Edition, if no other edition is the default).
For the second part of the URL (the query part), the 5 possible values are:
A value set with a URL that follows the pattern "[edition/version]?fhir_vs=isa/[sctid]" follows this template:
<ValueSet xmlns="http://hl7.org/fhir"> <text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"> [Some HTML that describes this value set as all concepts subsumed by sctid] </div> </text> <url value="[edition/version]?fhir_vs=isa/[sctid]"/> <version value="[edition/version]"/> <name value="SNOMED CT Concept [sctid] and descendants"/> <description value="All SNOMED CT concepts for [sctid or preferred description]"/> <copyright value="This value set includes content from SNOMED CT, which is copyright © 2002+ International Health Terminology Standards Development Organisation (SNOMED International), and distributed by agreement between SNOMED International and HL7. Implementer use of SNOMED CT is not covered by this agreement"/> <status value="active"/> <compose> <include> <system value="http://snomed.info/sct"/> <filter> <property value="concept"/> <op value="is-a"/> <value value="[sctid]"/> </filter> </include> </compose> </ValueSet>
The value set with a url that follows the pattern "[edition/version]?fhir_vs=refset" follows this template:
<ValueSet xmlns="http://hl7.org/fhir"> <text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"> [Some HTML that describes this value set as all concepts with associated reference sets] </div> </text> <url value="[edition/version]?fhir_vs=refset"/> <version value="[edition/version]"/> <name value="SNOMED CT Reference Sets"/> <description value="All SNOMED CT concepts associated with a reference set"/> <copyright value="This value set includes content from SNOMED CT, which is copyright © 2002+ International Health Terminology Standards Development Organisation (SNOMED International), and distributed by agreement between SNOMED International and HL7. Implementer use of SNOMED CT is not covered by this agreement"/> <status value="active"/> <compose> <include> <system value="http://snomed.info/sct"/> <!-- repeat: one concept element with a code for each concept that has an associated reference set --> <concept> <code value="[sctid]"/> </concept> <!-- end repeat --> </include> </compose> </ValueSet>
For each concept that is associated with a reference set, there will be one 'concept' element with a contained 'code' element that contains the sctid.
A value set with a url that follows the pattern "[edition/version]?fhir_vs=refset/[sctid]" follows this template:
<ValueSet xmlns="http://hl7.org/fhir"> <text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"> [Some HTML that describes this value set as all concepts in the reference set identified by sctid] </div> </text> <url value="[edition/version]?fhir_vs=refset/[sctid]"/> <version value="[edition/version]"/> <name value="SNOMED CT Reference Set [sctid]"/> <description value="All SNOMED CT concepts in the reference set [sctid or preferred description]"/> <copyright value="This value set includes content from SNOMED CT, which is copyright © 2002+ International Health Terminology Standards Development Organisation (SNOMED International), and distributed by agreement between SNOMED International and HL7. Implementer use of SNOMED CT is not covered by this agreement"/> <status value="active"/> <compose> <include> <system value="http://snomed.info/sct"/> <filter> <property value="concept"/> <op value="in"/> <value value="[sctid]"/> </filter> </include> </compose> </ValueSet>
A value set with a url that follows the pattern "[edition/version]?fhir_vs=ecl/[ecl]" follows this template:
<ValueSet xmlns="http://hl7.org/fhir"> <text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"> [Some HTML that describes this value set as all concepts that match the expression constraint ecl] </div> </text> <url value="[edition/version]?fhir_vs=ecl/[ecl]"/> <version value="[edition/version]"/> <name value="SNOMED CT Concepts matching [ecl]"/> <description value="All SNOMED CT concepts that match the expression constraint [ecl]"/> <copyright value="This value set includes content from SNOMED CT, which is copyright © 2002+ International Health Terminology Standards Development Organisation (SNOMED International), and distributed by agreement between SNOMED International and HL7. Implementer use of SNOMED CT is not covered by this agreement"/> <status value="active"/> <compose> <include> <system value="http://snomed.info/sct"/> <filter> <property value="constraint"/> <op value="="/> <value value="[ecl]"/> </filter> </include> </compose> </ValueSet>
Implicit concept maps are those whose specification can be predicted based on the grammar and/or content of the underlying code system, and the known structure of the URL that identifies them. This allows a single URL to serve as a concept map definition that defines a mapping between two sets of concepts, and which can serve as the basis for the $translate operation. SNOMED CT has two common sets of implicit concept maps defined:
Association Reference Sets are part of the core SNOMED CT distribution. The following standard Association Reference sets can be used for implicit concept maps:
Name | Concept Id | Relationship |
POSSIBLY EQUIVALENT TO | 900000000000523009 | inexact |
REPLACED BY | 900000000000526001 | equivalent |
SAME AS | 900000000000527005 | equal |
ALTERNATIVE | 900000000000530003 | inexact |
Simple Map Reference Sets (reference sets which are descendants of 900000000000496009 "Simple map") also define an implicit concept map.
If any ConceptMap resources exist with an identifier that conforms to the URL pattern specified below, the content of the resource must conform to the template provided. Canonical references to ConceptMap resource instances are made using their URI.A SNOMED CT implicit concept map URL has two parts:
The URL http://snomed.info/sct should be understood to mean an unspecified edition/version. This defines an incomplete concept map whose actual membership will depend on the particular edition being used. If no version or edition is specified, the terminology service SHALL use the latest version available for its default edition (or the International Edition, if no other edition is the default).
For the second part of the URL (the query part), there is only one possible value:
A concept map with a URL that follows the pattern "[edition/version]?fhir_cm=[sctid]" follows this template, where [name], [sctid] and [relationship] are taken from the table above:
<ConceptMap xmlns="http://hl7.org/fhir"> <text> <status value="generated"/> <div xmlns="http://www.w3.org/1999/xhtml"> [Some HTML that describes this concept map] </div> </text> <url value="[edition/version]?fhir_cm=[sctid]"/> <version value="[edition/version]"/> <name value="SNOMED CT [name] Concept Map"/> <description value="The concept map implicitly defined by the [name] Association Reference Set"/> <copyright value="This value set includes content from SNOMED CT, which is copyright © 2002+ International Health Terminology Standards Development Organisation (SNOMED International), and distributed by agreement between SNOMED International and HL7. Implementer use of SNOMED CT is not covered by this agreement"/> <status value="active"/> <sourceUri value="[edition/version]?fhir_vs"/> <targetUri value="[edition/version]?fhir_vs"/> <group> <!-- 0..* Same source and target systems --> <source value="http://snomed.info/sct"/> <sourceVersion value="[edition/version]"/> <target value="http://snomed.info/sct"/> <targetVersion value="[edition/version]"/> <!-- a mapping for each member of the reference set --> <element> <code value="[member]"/> <target> <code value="[reference set value]"/> <equivalence value="[relationship]"/> </target> </element> </group> </ConceptMap>
Maturity Level: n/a | Standards Status:Informative |
Applications can use the resources defined by FHIR by storing them natively in a database or persistent store, where different applications or modules write and read the resources as part of their implementation. This page describes implementation issues encountered when storing resources natively in persistent stores.
Note that almost all applications store the information found in resources in some persistent store - usually a database. Most applications store the information found in the resources in some internal format, and only use resources natively when exchanging with other applications. This page concerns applications that store the FHIR resources natively.
In principle, resources are designed for exchange between systems, rather than as a database storage format. One practical consequence of this is that in some way, resources are highly denormalised, so that granular exchanges are fairly stand alone. (Note that in some ways, resources are also highly normalised; e.g. Patient demographic details are only found in the Patient resource).
To illustrate this, consider using an RxNorm code as a medication code. In a prescription resource (MedicationRequest), that will look like this:
<MedicationRequest xmlns="http://hl7.org/fhir"> <medicationCodeableConcept> <coding> <system value="http://www.nlm.nih.gov/research/umls/rxnorm"/> <code value=""/> </coding> </medicationCodeableConcept> </MedicationRequest>
If the resource was designed to prioritize storage efficiency, it would be normalized so that the code was just some primary key reference:
<MedicationRequest xmlns="http://hl7.org/fhir"> <code key="123431232"/> </MedicationRequest>
or something similar. Note: Whether to normalise or not is an engineering design question that has multiple different considerations, and very often product designers change their decision about this for engineering reasons with no associated change in functionality or requirements.
Resources, on the other hand, are designed for robustness and stability over efficiency. Using a key reference like the second example would require all the participants in an exchange to synchronize the key for the code, which is often not possible, and rarely stable.
In spite of this design criteria, it can still be useful and appropriate to store resources directly in a persistent store or database. Whether to do so depends on an application's requirements.
If an application's information requirements are nailed down - that is, well understood, clearly expressed, and not subject to uncontrolled change – then it is easy to design a data storage schema that is completely fit for purpose and highly efficient compared to storing FHIR resources. Classic Enterprise Information Systems (EHRs) tend to behave like this.
If, on the other hand, the application's information requirements are not at all nailed down, and implementers have to deal with whatever data comes in an ongoing basis, then resources are actually a very sound way to store an application's data. The the extensibility approach makes FHIR a particularly robust choice as the primary data store. Clinical Data Repositories tend to behave like this.
Most information systems fall somewhere between these 2 extremes, and determinming whether to store resources directly is not straight forward. Some applications take a hybrid approach – storing FHIR resources natively, and storing a well controlled subset of information in some expressly designed persistent scheme. The balance between these is driven by the stability of information requirements for different parts of the system.
Very often, applications storing FHIR resources natively must deal with multiple different FHIR versions, since they are receiving information from different systems with different timelines for adopting ongoing FHIR releases.
Typically, such systems have functional requirements that include some variation of these:
There is no single pattern to resolve these somewhat inconsistent requirements, but application designers can consider several different techniques for dealing with these kind of requirements:
A wide variety of technologies exist for storing resources natively, including:
This specification does not recommend any particular approach. The rest of this page describes general information management considerations that apply across all technologies.
Most applications that store resources natively find the way references work in FHIR deserves particular focus. References can be absolute or relative URLs, they can be version specific or not, they may or many not follow FHIR’s well defined RESTful interface pattern, and they may or might not resolve in the local system. In addition, given the requirements consideration above, it's not always possible to enforce referential integrity when storing resources directly.
All the flexibility is required in various exchange scenarios, but it can present challenges for application design when building a coherent data store with resources.
Applications that store resources natively may want to extending the storage
format with an element to capture the resolved link
in addition
to the existing reference/identifier in the Reference
and canonical data types.
The RDF format does this explicitly for references and codings (fhir:reference and fhir:concept).
Applications that store JSON, will have to remove the extension for exchange, unless a native FHIR extension is used, which might not be the most efficient way to store the resolved link.
Note to balloters: Is there enough interest to standardize an extension? Ballot comments are welcome.
Maturity Level: N/A | Standards Status:Informative |
See MedicinalProductPackaged examples for examples using SubstanceAmount.