Customer Interface Requirements: Logical ids

1 Overview
2 Requirements

Overview

Logical ids are the primary keys of FHIR resources. This page outlines the requirements surrounding this data element to successfully use the FHIR interface.

Requirements

We will use the following Condition as an example to demonstrate the requirements of the interface around logical ids.

{
  "resourceType": "Condition",
  "id": "e076be2d-f663-3b04-9b76-2d0ac968be92",
  "identifier": [
    {
      "system": "http://fhir.smiths-hospital.com/id/legacy-identifier",
      "value": "45162"
    }
  ]
}

In this example the logical id is e076be2d-f663-3b04-9b76-2d0ac968be92. It is not 45162, which is a business identifier.

Logical ids are the sole authority by which data is identified for update, deletion or reference by other resources within the FHIR server. There is no soft matching on resource element data of any kind. It is therefore critical that the customer’s approach to logical ids is concrete and sound.

Logical ids must be:

Stable: the same data point in the same system must always be sent with the same logical id to be able to effectively update or delete it.
Guaranteed unique to a given upstream instance: if different data points are sent with the same logical id, they will silently overwrite each other. There is no validation to stop this within the customer interface, it is purely down to customers to manage. There are severe clinical safety and IG consequences for failing to adhere to this principle. If multiple data feeds from different source systems are being fed into a single FHIR server, these logical ids must be namespaced to guarantee uniqueness: the inherent uniqueness of logical ids within a single source system should not be interpreted as uniqueness across different source systems.
Strings: logical ids do not have to be UUIDs, but this is generally seen as most desirable.

If a data point is sent into the FHIR endpoint without a logical id, the FHIR server will generate a unique logical id and assign it to that data point, including it in the response returned to the customer. It is possible to then utilise this logical id for subsequent interactions with that data point, but this requires exceptionally careful managing of the logical ids on the customer’s side of the interface to match it to the appropriate data point, which almost inevitably falls back on soft matching of some kind. For this reason, this is an integration pattern which is strongly discouraged.