FHIR Implementation Guide
This is a temporary page with changes regarding issue MM-1457. See official publication here. |
Inhoud
- 1 Introduction
- 2 Use case overarching principles
- 2.1 Content Types and encodings
- 2.2 Use of coded concepts
- 2.3 Use of the reference datatype
- 2.4 Relating FHIR profiles with their functional definitions
- 2.5 Profile use and declaration
- 2.6 Resource.text or "the narrative"
- 2.7 Search
- 2.8 Usage of the id and fullUrl elements in FHIR instances
- 2.9 Handling errors
- 3 FHIR Packages
1 Introduction
This implementation guide describes the considerations for using HL7® FHIR® in context of information standards that are maintained by Nictiz. It applies specifically to HL7® FHIR® version 3 (STU3).
This implementation guide is aimed at software vendors and developers that need to implement FHIR based information standards maintained by Nictiz. Users of this guide are expected to be familiar with the FHIR STU3 specification and resource processing. Where relevant, links to the FHIR specification are provided. This implementation guide is not intended to be a tutorial on that subject.
2 Use case overarching principles
2.1 Content Types and encodings
Unless stated otherwise, the information standards use the FHIR RESTful framework. This framework defines at least three content-types to send/retrieve information:
- XML: application/fhir+xml
- JSON: application/fhir+json
- RDF: text/turtle - Not supported in this context
Servers SHALL support both XML and JSON, while clients MAY use either format for the request and the response. For the response, servers SHALL support server-driven content negotiation as described in the FHIR specification. This means that clients can indicate the desired response format using the optional _format=[mimetype]
URL parameter, or the acceptable response format(s) using the Accept
header. The URL parameter takes precedence over the header. If a client does not request a specific content-type, then it is server discretion to respond using XML or JSON.
FHIR uses UTF-8 for all request and response bodies. Since the HTTP specification (section 3.7.1) defines a default character encoding of ISO-8859-1, requests and responses SHALL explicitly set the character encoding to UTF-8 using the charset
parameter of the MIME-type in the Content-Type
header. Requests MAY also specify this charset
parameter in the Accept
header and/or use the Accept-Charset
header.
2.2 Use of coded concepts
Coded information is extremely important for interoperability between systems. It enables systems to act on information rather than have humans read everything for interpretation - it enables medication related alerts, exercise encouragements because of weight increase, and many more things. In the HCIMs and profiles, we therefore strive for complete coverage of all possible situations.
However it is likely that unknown codes present themselves in the communication, for example because the sending system has updated its medication codes to a newer version than the receiving system, or because an older record item is coded in a way that now has been deprecated. It is therefore vital that, in addition to the code itself, the sender includes the semantics of the code. Therefore, systems SHOULD include (CodeableConcept.)coding.display and/or CodeableConcept.text for coded data in FHIR instances. These fields may only be absent in rare circumstances, for example when dealing with historic data, or in data acquired without such info from a third party.
2.2.1 Mapping of coded concepts
Terminology from HCIMs or UCSDs (use case specific datasets) needs to be faithfully applied to the FHIR profiles, but this is not directly possible when the base FHIR resource defines required terminology that bears no direct relationship with the HCIM or UCSD. These cases include, but are not limited to, the FHIR resource elements of datatype 'code' (Patient.gender, status elements, structural type elements, etc.). This datatype always describes FHIR specific terminology, which usually doesn't align with the HCIM/UCSD terminology.
In these cases, a mapping will be provided to explain the relationship between de HCIM/UCSD terminology and the FHIR terminology. This is normally done through a FHIR ConceptMap, which can translate between the terminology used in the HCIM/UCSD, and the terminology that FHIR instances need to adhere to. Usually, the original terminology from the HCIM/UCSD will be communicated as well by adding the extension code-specification on the same element. This allows unambiguous interpretation on the receiver end.
Example snippet from an AllergyIntolerance where both the FHIR terminology high and the SNOMED CT 24484000 terminology are communicated. The FHIR terminology is obtained from the HCIM terminlogy using ConceptMap MateVanKritiekZijnCodelijst-to-allergy-intolerance-criticality:
<criticality value="high">
<extension url="http://nictiz.nl/fhir/StructureDefinition/code-specification">
<valueCodeableConcept>
<coding>
<system value="http://snomed.info/sct"/>
<code value="24484000"/>
<display value="Severe"/>
</coding>
</valueCodeableConcept>
</extension>
</criticality>
Please note: Unfortunately, FHIR doesn't have a core structured way for indicating which ConceptMaps to use. Instead, mappings are documented in the description of the element in the profile and/or specifically on the mapping description contained in the element.
To retrieve the indicated ConceptMap on Simplifier, the canonical url from the description needs to be used as search term. We are still examining ways to make this more user friendly, for example by using the extension for ConceptMaps, but that does not work unless various third party tooling is updated.
2.3 Use of the reference datatype
FHIR resources act like the internet where resources point to each other through references. The reference datatype is comparable to web pages pointing to other web pages, scripts and images. Each reference may be either internal or external. The datatype supports a display attribute, comparable to a link title in a web page, and an identifier. The identifier acts as a logical reference when the literal reference is not known. Literal references work based on the FHIR logical id, not the identifier, attribute.
Name | Flags | Card. | Type | Description & Constraints |
---|---|---|---|---|
Reference | Σ I | Element | A reference from one resource to another + SHALL have a contained resource if a local reference is provided + SHALL have a reference or identifier unless specified otherwise * | |
reference | Σ | 0..1 | string | Literal reference, Relative, internal or absolute (not preferred) URL |
identifier | Σ | 0..1 | Identifier | Logical reference, when literal reference is not known |
display | Σ | 1..1 | string | Text alternative for the resource |
In a loosely coupled context it is usually good practice to include information rather than have systems progressively retrieve it. When the FHIR servers are in fact a facade on non-FHIR systems, it may not be possible to build external references from the resource id, as non-FHIR systems may not support that concept. Example: a resource for the general practitioner will have an AGB and/or UZI identifier in any information system, the id for the same resource might not be known anywhere. The expectation is therefore that the vast majority of references will be based on internal references or identifiers.
The basic requirements for using references in this context are:
- The reference, if used, SHALL be resolvable
- External references SHALL be regarded in the same context as the resource itself. For internal references, this is guaranteed by default. If the current security context is insufficient for retrieving the reference, then additional negotiation for appropriate privileges may be required.
- External references are preferably relative as opposed to absolute.
- The display attribute SHALL be used to provide a very short description of the target resource.
Note: there is a known weakness in the Reference datatype for FHIR STU3 which is fixed in FHIR R4. When the reference datatype element could point to multiple types of resources, e.g. Patient.generalPractitioner reference(Organization | Practitioner), you cannot know what type is meant when you only have an identifier for reference. For this reason:
* Note: the Reference datatype SHALL have a reference or identifier unless specified otherwise. There is a known limitation in some of the FHIR STU3 resources where the appropriate reference type is not available. Examples include PractitionerRole which is missing from Encounter.participant (prevents proper context of the attending physician) and Patient which is missing from Media.operator (prevents patient-generated Media). In such cases, an extension will contain the reference of the appropriate type. This leads to slight duplication: the original Reference.display will be duplicated into the Reference.extension.valueReference.display. Systems that do not know about the extension would thus still have access to the regular Reference.display.
- Literal (internal/external) references are preferred over logical references when a choice in resource type is available.
2.4 Relating FHIR profiles with their functional definitions
All profiles have a traceable relationship with their functional counterpart(s) based on the element mapping mechanism in FHIR. This allows to:
- define one or more references from a FHIR profile to an external URL where the functional definition can be found
- define for each FHIR profile element to which concept within a functional definition it corresponds
The functional definition(s) underlying the profile can thus be resolved using the StructureDefinition.mapping metadata field of a profile. To relate a FHIR profile field to a concept from the functional description, the concept ID defined in the DataElement.mapping can be used to look up the concept in the functional definition. It is possible that a single profile element refers concepts from multiple functional descriptions. Simplifier will show an onverview of all the mappings for a FHIR profile on the dedicated 'mappings' tab, together with a clickable URL to the functional definition. In addition, on the 'overview' tab for each field the relevant mapping can be found.
For example, the profile nl-core-address defines a relationship with with four functional definitions, one of which is AddressInformation-v1.0(2017EN). This mapping is identified within the profile using 'hcim-addressinformation-v1.0-2017EN'. Looking at the 'Address.city' element in this profile, one of the mappings is defined as 'hcim-addressinformation-v1.0-2017EN:NL-CM:20.5.3'. This reveals that this element implements (amongst others) the concept from the HCIM AddressInformation-v1.0(2017EN) described using ID 'NL-CM:20.5.3'.
2.5 Profile use and declaration
The implementation guides for the various information standards list the profiles to use for the FHIR resources. In the interest of interoperability it is important that, when using said information standard:
- Each resource SHALL be a valid instance of the applicable profile. Note that this applies not only to profiles listed directly in the IG, but also to profiles referred from/used by listed profiles.
- Each resource SHALL include the canonical URL of this profile in the
meta.profile
element. The canonical of compatible base or derived profiles MAY be included as well.
2.6 Resource.text or "the narrative"
The FHIR STU3 specification says instances SHOULD contain a human readable summary of the contained data, which can be used as fallback by the receiver. This human readable text is contained in the text
element with datatype "Narrative". This human readable text is often referred to as "the narrative".
This implementation guide has the following expectations regarding the use of narratives:
- Senders SHALL provide a "clinically safe" (see below) narrative of status "extensions" (preferred) or "generated" (see below), unless:
- The resource does not support narratives. This is the case for resources that do not derive from DomainResource, like Binary.
- The resource is contained in another resource.
- It is explicitly documented in the information standard to do otherwise.
- Receiver SHALL support the narrative. Ignoring the narrative is considered passive support. Support for the narrative SHALL be in accordance with the status and explicitly documented use in the relevant information standard.
- Receiver SHALL NOT generically depend on presence of a clinically safe narrative as their only means to present data to users when an explicitly documented use case for status empty or additional exists. Also, using just the narrative you would not expect to produce graphs, support for medication alerts and other functionality.
2.6.1 "Clinically safe" narratives
Regarding the contents of the narrative, the FHIR STU3 spec states that:
The narrative need not encode all the structured data, but is required to contain sufficient detail to make it "clinically safe" for a human to just read the narrative.
And for the Narrative datatype:
Structured data SHOULD NOT generally contain information of importance to human readers that is omitted from the narrative. Creators of FHIR resources should not assume that systems will render (or that humans will see) data that is not in the narrative.
The decision to what entails "clinically safe" information, is somewhat arbitrary. Guidelines for "clinically safe" inspired by the FHIR W5 report:
- If you only had the narrative: the intention and context should be clear to you.
- Who. Patient/subject, performer, author and/or other primary actors. Is this about family history or the actual patient.
- What. The topic for the resource is clear.
- When. Is this past, present, or future information.
- Why. What led up to the event. E.g. Condition, Referral that caused Encounter or Procedure.
- Where. Location of the event/action in the resource.
- Context. Relevant context as present as presented in the resource. status, Encounter, EpisodeOfCare, Diagnosis, Condition, BodySite.
- Rendering every identifier and/or code detail may not be necessary. Resource.text is for human assessment of the situation so emphasis should be on display text, representing identifier/code/system as relevant in the context.
Informal note: Producing a "clinically safe" narrative can be cumbersome. Various reference frameworks like HAPI include a Narrative Generator of some sort.
2.6.2 Narrative status
Datatype Narrative defines different status codes to indicate the origin of the narrative text. This implementation guide expects the most common use case to be the status "extensions", which means that the narrative is generated entirely from the structured data and the extensions used. The reason for this is that most resources can have extension content defined on them. This status can still be used if a particular instance doesn't contain any extensions.
Alternatively, status "generated" may be used if the sender did not anticipate inclusion of regular extension content in the narrative.
Note: for both status "extensions" and "generated", all modifier extensions SHOULD be included in the narrative as they always affect the semantics.
Senders SHOULD NOT use the other possible statuses unless it is explicitly documented why, e.g. in an information standard. Receivers MAY choose to support narratives with status "additional", which means that it holds information not contained in the structured data. Receivers - upon rendering narrative with status "additional" - SHOULD make it clear to the user that the information is a fragment, and not the entire thing, in some suitable way.
2.7 Search
2.7.1 Search URLs and search parameters
Each use case of the various information standards lists the search parameters to use for a client to query the relevant information on a server. Usually, this is done in the form of (a number of) search URL(s), although individual use cases may use some other form if necessary (for example, listing optional parameters). Regarding the search parameters, the following guidelines apply:
- Unless explicitly marked as optional, the listed search parameters are considered the minimum for a request, meaning that:
- All stated parameters and modifiers SHALL be supported both by clients and servers.
- All stated parameters and modifiers SHALL be used for searching as specified in the information standard.
- A client MAY use additional search parameters in the search (such as date-range) not defined in the information standard. These may serve to further constrain the result set.
- A server MAY ignore and MAY support additional search parameters. A server SHALL report the applied parameters in the self-link of the response and SHOULD provide additional information about the search process using an OperationOutcome in the search-result Bundle (as an entry with
search.mode
set to "outcome"). A client MAY use the self-link and/or OperationOutcome to inform the user, independently apply these filters to the result set, or take some other action. - A server SHALL reject any search request that contains parameters suffixed by a modifier that the server does not support for that parameter. For example, if the server supports the name search parameter, but not the :exact modifier on the name, it should reject a search with the parameter
name:exact=Bill
, using an HTTP400
error with an OperationOutcome with a clear error message. - A server SHALL NOT return information that is out of scope for the defined use case or authorization, even if the request by the client is wider than the use case.
- Repeating search parameters constitute a logical AND. Repeating search parameter values constitute a logical OR. Where applicable, this will be described further in the implementation guide.
- The order of the search parameters is always irrelevant.
General guidance on the use of search parameters can be found in the FHIR specification.
2.7.1.1 Search on date, number or quantity
When a search parameter has a type of date, number or quantity, the request uses prefixes to control the search behavior. Unless explicitly stated otherwise, the minimum set of supported prefixes for these types is eq
, gt
, lt
, ge
and le
. For example:
GET [base]/Observation?date=ge2019-01-01&date=le2020-01-01
Searches on all Observation resources that have an effective[x]
between January 1, 2019 and January 1, 2020.
2.7.1.2 The _lastUpdated
search parameter
Retrieving information that was added, changed, deleted relative to a date may be done using the search parameter _lastUpdated
, which is available for any resource. Using the parameter _lastUpdated
, a system may query for data that is new since a specified date. Any FHIR server is expected to support this parameter. More information can be found in the section on _lastUpdated
in the FHIR specification.
An example search request is shown below.
GET [base]/Consent?category=http://snomed.info/sct|11291000146105&_lastUpdated=gt2018-10-01
This search finds all Consent resources with a category SNOMED code 11291000146105 that have been modified since Oct 1, 2018.
2.7.2 Search results
2.7.2.1 Including referenced resources
Servers may not support read interactions, but all references from search results need to be resolvable (see #Use of the reference datatype). Therefore servers MAY choose to include the referenced resources in the searchset Bundle, even if the client didn't use any _include
parameters. These resources SHALL have Bundle.entry.mode
set to "include". Servers SHOULD NOT use contained resources for this purpose.
2.7.2.2 Paging
Servers MAY use paging for performance reasons. Client SHALL support this mechanism to prevent loss of information.
2.8 Usage of the id
and fullUrl
elements in FHIR instances
2.8.1 id
versus identifier
FHIR recognizes two fields that are used as identifier for instances: id
and identifier
. Although these are both identifiers, they are unrelated and serve a completely different purpose:
id
is the logical identifier, or technical identifier, akin to the id-field in a database. It is used as a unique handle for every instance on a particular server, and is needed to construct the URL to the instance. As such, it is used for referring between resources. Theid
has no further meaning outside of the server.identifier
is a business identifier, which has a meaning outside of the server. Examples are a registration number of a healthcare provider, a BSN or social security number for citizens, ISBNs for books, etc. Any instance may have multiple kinds of identifiers.
This section is about the id
field and more general about the concept of a logical/technical id to identify instances on a server. The usage of the identifier
field, i.e. the business identifier, cannot be described in general terms and will be dictated one a use-case basis by the particular profiles.
2.8.2 When is id
expected?
As stated above, the logical id is meant to uniquely identify instances on a particular server; it is a vital component when using FHIR within a RESTful context. So as a rule of thumb, the id
element should always be present when dealing with instances that have a logical id, thus with instances on a server. This means:
- Any operation where an existing instance on the server is addressed, like reading or updating, needs a logical id to target said instance for the URL. In these cases,
id
field SHALL be populated in both the request and the response, and it SHALL match the id in the URL. - When a client sends a new instance to a server using a create operation, the
id
element is not expected to be present, but the server SHALL populate it in the response. This is because upon sending, these new instances don't exist yet on the server, so a logical id has no meaning. But whenever it is created on the server, it should get a logical id assigned by the server. (Note: it is not strictly prohibited to populate theid
field when sending a new instance, but the server SHOULD ignore it). - When a client performs a search on a server, all instances in the returned searchset Bundle SHALL have the
id
field populated. Note that in some situations, servers might not support logical id's, for example when it is a stateless middleware server that gets its input from a non-FHIR XIS backend. If this is the case and if the use case doesn't require read support, a single use UUID or an OID may be used to populate theid
field; however, a server SHOULD try its best to populate it with a meaningful value.
2.8.3 Logical ids, fullUrl
s and references in Bundles
There are several FHIR operations, like searching or batch create operations, where multiple instances are placed together in a Bundle. These instances will usually contain references to each other. These internal references cannot be resolved simply by inspecting the id
element of every instance; it is not guaranteed that all instances have a logical id. Instead, Bundles allow an entry.fullUrl
element for each instance which may be used for references. This is an additional mechanism to the logical id, not a replacement:
- The guidelines above for populating the
id
field still apply. - If
id
is present,fullUrl
SHALL correspond with it (see below).
fullUrl
s may be RESTful URLs, UUIDs or even OIDs, based on the situation (which may be mixed within the same Bundle):
- Instances with a logical id
- If an instance can be accessed on the server using RESTful operations, the
id
of that instance in the Bundle will be populated. The correspondingfullUrl
in this case SHALL be the absolute URL to the instance on the server.Instances within the Bundle may use relative references to each other, like they are on the same server. The FHIR machinery specifies how to find the matching instance based on the
fullUrl
. - Instances without a logical id
- When instances are to be created on a server or when the server doesn't support reading individual instances, they don't have a logical id. When these id-less instances need to be referenced from within a Bundle, there are two alternatives:
- UUIDs can be used as single-use ids that will change each time the Bundle is generated. The
fullUrl
for the instance will be the UUID prefixed withurn:uuid:
, while theid
field (if present) is the unprefixed UUID. - OIDs can be used if the instance has an OID-based business identifier (i.e. the
identifier
field), like the UZI number of a healthcare provider. ThefullUrl
will be the OID prefixed withurn:oid:
, while theid
field (if present) is the unprefixed OID. However, the use of OIDs as id has some limitations:- The
id
has a maximum length of 64 characters, so only OIDs that contain less than 64 characters can be used. - OID-based id's are expected to be stable, just like RESTful ids. Different Bundle instances SHALL always use the same OID-based ids.
- The
- UUIDs can be used as single-use ids that will change each time the Bundle is generated. The
- Instances within the Bundle should use the prefixed version of the UUID/OID for referencing.
2.8.3.1 Example
Consider a client that wants to send a new Observation instance to a server and simultaneously link it to an existing Task instance. This can be done using a transaction Bundle:
<Bundle xmlns="http://hl7.org/fhir">
<!-- Transaction Bundle that will simultaneously create a new instance and update an existing one -->
<type value="transaction"/>
<!-- A new instance to create -->
<entry>
<!-- The new instance doesn't have a logical id yet, so a temporary UUID is used for references within the Bundle -->
<fullUrl value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e"/>
<resource>
<Observation>
<!-- The id field is absent, because the instance doesn't exist yet on the server -->
...
</Observation>
</resource>
</entry>
<request>
<method value="POST"/>
<url value="Observation"/>
</request>
<!-- An existing instance to update with a reference to the new instance -->
<entry>
<!-- RESTful URL of existing Task instance -->
<fullUrl value="http://example-xis.com/Task/1234"/>
<resource>
<Task>
<!-- Logical id of the instance, matches the fullUrl -->
<id value="1234"/>
...
<output>
...
<valueReference>
<!-- Reference to the fullUrl of the new instance -->
<reference value="urn:uuid:0e855422-b8ef-4247-9443-f3747e78747e"/>
</valueReference>
</output>
</Task>
</resource>
<request>
<method value="PUT"/>
<!-- The path on the server, consistent with fullUrl and id -->
<url value="Task/1234"/>
</request>
</entry>
</Bundle>
The server response should then look like:
<Bundle xmlns="http://hl7.org/fhir">
<type value="transaction-response"/>
<entry>
<!-- The newly created instance gets the logical id "5678" from the server -->
<fullUrl value="http://example-xis.com/QuestionnaireResponse/5678"/>
<resource>
<Observation>
<!-- The id matches the fullUrl -->
<id value="5678"/>
...
</Observation>
</resource>
</entry>
<response>
....
</request>
<entry>
<fullUrl value="http://example-xis.com/Task/1234"/>
<resource>
<Task>
<id value="1234"/>
...
<output>
...
<valueReference>
<!-- Reference to the relative URL of the created instance may be relative -->
<reference value="Observation/5678"/>
</valueReference>
</output>
</Task>
</resource>
<response>
....
</response>
</entry>
</Bundle>
2.9 Handling errors
Errors in FHIR interactions are usually communicated using the combination of an appropriate HTTP status code in the 4xx-5xx range, and an OperationOutcome resource providing more details regarding the error. The OperationOutcome resource contains mandatory elements to indicate the overall type and severity of the error (respectively code
and severity
) and MAY express the location (using location
or expression
) and a free-form or coded description of the error (using the diagnostics
or detail
element). Although these latter elements are not required, their usage is strongly encouraged.
For the most common errors, the expected handling is listed in table [xxx] below. This should be interpreted as a guideline, as the nature of an error is not always unambiguous and various FHIR reference implementations will make different choices. The FHIR specification provides more detail on error handling in general and for search operations specifically.
In general, most FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues) will result in one of these HTTP status codes:
- 400 Bad Request - resource could not be parsed, search could not be processed or basic FHIR validation rules failed
- 401 Not Authorized - the authorization is required for the interaction that was attempted
- 404 Not Found - resource type not supported, or not an FHIR endpoint
- 422 Unprocessable Entity - the proposed resource violated applicable FHIR profiles or server business rules
Interaction | Error | Expected action | Example |
---|---|---|---|
All | Invalid authorization |
|
Example |
Resource is not supported |
|
Example | |
search
|
No match for the given search parameters | This is not considered an error; a normal Bundle of type "searchset" is returned containing 0 entry's
| |
Unkown or unsupported search parameter value. This situation applies to non-supported HCIM profiles when the Resource endpoint itself is supported. |
|
Example | |
Syntactically incorrect parameter |
|
Example | |
read
|
Read request with unknown id |
|
Example |
update
|
No or incorrect Resource id |
|
Example |
create /update
|
Resource syntax or data is incorrect or invalid |
|
Example |
3 FHIR Packages
MedMij adopts the FHIR Packaging mechanism to support consistent versioning of profiles and related conformance resources such as OperationDefinitions. FHIR Packaging is based on the NPM Packaging mechanism and offers developers a convenient way to include the conformance resources in their favorite IDE. The relevant package version is indicated and linked in the information standards technical design page.
For even more background information:
- What is the problem that packaging could address
- Introducing the Simplifier FHIR Package Server (includes what problem packaging addresses)
- Firely Torinox introduction (this is one of the tools that's useful for working with FHIR packages)
- The HL7 wiki that outlines the base specification
It is not required to implement FHIR based information standards using the packaging mechanism. It is still possible to download all or selected resources from Simplifier on as-needed basis. You are however encouraged to invest in dealing with packages. |