Interweave Implementation Guide
0.1.0 - ci-build
Interweave Implementation Guide - Local Development build (v0.1.0). See the Directory of published versions
FHIR provides a set of “complex datatypes” which act as building blocks for all other resources. Several in particular have been found to be extremely important to a successful implementation:
FHIR provides extensive and helpful guidance at the above links, and this should be studied. However this page highlights key points and offers additional guidance on how these building blocks are used for a Shared Care Record implementation.
A fundamental challenge for any Shared Care Record is to balance two different goals:
The CodableConcept tackles this challenge by offering a data structure which can include:
To meet the above two goals, a data provider must consider:
a) Capturing exactly what the user entered
b) Capturing standard coding for machine analysis
Looking at it another way, this means that:
Other points of note:
A “coding” entry must always include “coding.display” wording. (Noting some rare exceptions where no display value exists, in which case this is impossible)
The coding.system must always be populated. (For local codes it is suggested to devise a unique uri - for example based on the url of the local FHIR server)
When displaying a Codeable Concept to the user then a Data Consumer should attempt to use in priority order:
The “text” content
The “coding.display” string from the coding entry marked as “userSelected”
The “coding.display” string from the first (and probably only) other coding entry
If none of these yield text to display then it is an error and cannot be displayed.
A Reference enables the creation of linkages between resources. This is an essential part of creating a rich web of interlinked data which users can browse. There are potentially three parts to a Reference:
1. The “reference” URL
This MUST always be populated and MUST always be resolvable. That is, it MUST always be possible to “follow” it to retrive a FHIR resource.
In most cases this will point at another locally hosted resource.
However there can be situations where this is not possible. This is particularly likely when referencing external items - for example locations where a patient is discharged to (their house, another care facility), and similarly for external practitioners and organisations. In this case the organisation authoring the resource will not hold definitive reference data about this item
The solution in this case is to use a Contained Resource. FHIR offers this mechanism to allow the referenced resource (eg a location in this example) to be incorporated within the main resource (eg Encounter). This allows the information to be shared as a one-off - without the need to store and maintain it on an ongoing basis. The “reference” is then an internal URL, providing an internal pointer within the same FHIR Resource.
2. “Display” text
This is a short string to describe the referenced item.
For straightforward reference data about people and places this MUST always be populated with the name.
Specifically:
Patient: name (eg prefix, given name, family name)
Practitioner: name (eg prefix, given name, family name)
RelatedPerson: name (eg prefix, given name, family name)
Location: name
Organisation: name
These resource types are very commonly used, and it is a valuable optimisation to make these resources usable stand-alone without a data consumer having to retrieve numerous additional FHIR Resources just to provide a basic display.
The standard FHIR Appliance will populate the above reference “display” texts automatically with up-to-date values
For other resource types the display text MAY be populated, but there is more to consider:
Complex clinical resources cannot necessarily be summed up accurately and safely in a short string
Often the referencing resource already contains other fields (eg a code or string) which are intended to provide the necessary summary
It is, of course, also possible to instead use _include which - although less efficient - does retrieve the whole resource to inspect and select from for display
3. An “identifer”
This MAY be used to uniquely identify the referenced item
FHIR offers the “id” field, to contain a unique identifier for each resource (often a guid).
However most FHIR Resources also offer an “identifier” field to capture a more meaningful and/or business-related identifier.
In some cases there is an obvious recognised identifier to use, for example:
However in many cases there is no such widely recognised identifier. Still, it can be useful to provide a local identifier - that helps to identify the item and may, for example, be useful to quote in enquiries and correspondence.
The pattern for this is established by Care Connect, which has chosen to use a single code system to denote a local identifier for a particular type of resource from ANY source. For example on the patient https://fhir.nhs.uk/Id/local-patient-identifier. This has the advantage of making local identifiers consistent to find, as well as enabling their use to be defined in a Profile via “slicing”.
Building on this approach we have defined similar code systems for other types of FHIR Resource.
A downside of this approach is that the local identifiers from different sources may overlap. We therefore propose a simple mitigation, based on prefixing the identifier with the organisation’s ODS code (with a period as separator)
Example: The organisation with ODS code “ABC” has an item with an identifier “12345”. The local identifier to be used in FHIR Resources is therefore “ABC.12345”