This page is part of the FHIR Specification (v3.3.0: R4 Ballot 2). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

7.12 Managing Resource Identity

FHIR Infrastructure Work Group

Maturity Level: 4

Ballot Status: Normative

Normative Candidate Note: This page is candidate normative content for R4 in the Infrastructure Package. Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.

Each resource has a known identity, which is a URL. The identity is not stored inside the resource, but must be tracked by systems handling resources. For RESTful systems, the resource identity is the same as the URL by which it is found. When a resource is packaged in a bundle (e.g. for messages, documents, or exchanged in a service), the id is included along with the resource. When systems using FHIR resources are deployed in an implementation context where there are more than two systems exchanging resources, the way that resources are identified with URLs needs to be managed carefully.

Note that many resources also have an identifier element, and usually there can be multiple identifiers. This identifier is a logical identifier for the concept that the resource describes and is different from the identity discussed in this section, which is the literal identity of the resource. Note that there are often multiple resource instances that describe the same concept across multiple systems, e.g. each application keeps its own copy of the patient information in a Patient resource. This can even exist within a single system, such as in the case of patient duplicates).

Some resources have a special identifier, which is constrained to be a proper URI, and which is known as the 'canonical URL' for the resource. These resources are referred to by this URI, which is encouraged to be an actual URL that resolves to a web page (or web service) that describes the content (hence 'canonical URL' not 'canonical URI', though this is also for legacy purposes).

7.12.1 Using Resources

Resources are used in a variety of circumstances. Generally, these can be categorized into 3 different scenarios:

1. Closed Trading System: the resources are only ever exchanged between fixed systems in a tightly controlled community, such as a single EHR system with multiple modules. There is only one master server for each resource type, and resources are managed by that server. In this context, the logical id of a resource is sufficient to fully identify the resource
2. Open system: there are many peer servers, each managing a set of resources of different types. In order to identify resources, a full URL reference to the origin server is required. The grand example of an open system is the World Wide Web
3. Partially closed, inter-linked systems: a mixture of both closed and open systems - trading communities that are tightly managed, but have managed interactions with other closed trading systems, or with the world-wide web, or both. In fact, this combination appears to be the most likely scenario for current real-world healthcare business solutions

These combinations are why either relative (logical) or absolute references are allowed, and why a logical id is always required, in order to enable seamless exchange amongst partially closed trading systems.

7.12.2 Copying Resources and Re-identification

When resources are exchanged between systems, they may need to be re-identified (i.e. assigned a new logical resource id). When a resource is re-identified, nothing in the resource change other than the Resource.id, but any references that point to the resource need to be updated. Whether re-identification is required or not depends on the context, as does how resource references are updated.

The normal case is that a client/receiving system accepts the server/sender's identification of a resource at face value, whether it is a relative or absolute reference. When the client/receiver wants to follow resource references, they are done using the server id (typically either by http calls or locating them in a bundle), but other arrangements are possible. In such cases, there is no need for re-identification.

Another scenario is for a client to retrieve a resource from a server and make its own local persistent copy. If the local resource has a life-cycle of its own (i.e. it is not just a cached resource), then it needs to have its own identity; i.e. the resource must be re-identified. The simplest case is that the client is only keeping local copies of resources from a single server. In these cases, the client can simply replace the Base URL and keep the logical id of the resource the same. In fact, if the server is using relative references, then this change doesn't involve any actual changes to the resources, it only means a re-interpretation of the references.

In some cases, however, the client may deal with multiple servers. In this case, the logical id of the resource is not guaranteed to be unique (unless all resources have a UUID for the logical id, which is allowed but not required). When the client cannot be sure that the resource identities are unique, it will have to re-identify the resources. In practice this means that the client needs to keep some kind of identity translation table, and update references to the resources it has copied locally when other resources are received.

The case of a gateway system that migrates resources from one ecosystem to another is very similar. In some limited cases, it can leave the logical id of the resources unchanged as resources are copied from one closed system to another. However, in more complicated cases, it will have to modify the resource references as resources pass across the gateway.

Implementer Note: In its current form, FHIR allows various convenient implementer practices around resource identification that make integration across eco-system boundaries more difficult. In particular, either only allowing UUIDs for logical IDs or only allowing absolute references would make the boundary management problem easier but remove useful and convenient flexibility for other uses of FHIR. Implementers should design their systems accordingly.

7.12.3 Consistent Resource Identification

Irrespective of changes to the logical id, the other identifiers in the resource (typically, .identifier and .url) remain unchanged as the resource moves from system to system, and these are the preferred basis to recognize the same content on different systems. E.g.

  GET http://a.company.example.com/Patient/23
  
  <Patient xmlns="http://hl7.org/fhir">
    <id value="23"/>
    <identifier>  
      <system value="http://a.particular.system/identifier"/>
      <value value="123456"/>
    </identifier>
  </Patient>

  GET http://other.company.example.com/fhir/Patient/5860200e-0ee3-42f5-8095-506e18dc9ca2
  
  <Patient xmlns="http://hl7.org/fhir">
    <id value="5860200e-0ee3-42f5-8095-506e18dc9ca2"/>
    <identifier>  
      <system value="http://a.particular.system/identifier"/>
      <value value="123456"/>
    </identifier>
  </Patient>

Given this, the patient resources can be interpreted to mean that they describe the same patient. For this reason, systems SHOULD:

• Only assign identifiers to resources when they uniquely identify the real world entity that the resources match (e.g. do not use account numbers as patient identifiers when multiple different patients share the same account number)
• Preserve identifiers as much as possible and not throw them away. Even if the identifiers are not useful to the system itself, they are likely to be useful to downstream consumers
• When serving resources, use consistent identifiers from the master persistent store where ever possible (e.g. when a resource is created from a primary record, populate the identifier, and store the identifier somewhere so the same identifier is used next time)

Following these practices will make for consistent identification of concepts and real-world entities across healthcare eco-systems. For example, medication orders can be represented as MedicationRequest and MedicationStatement. Some systems - primary sources - will provide the medication order as a MedicationRequest while other secondary systems will provide them as a MedicationStatement. Any system processing the resources will need to reconcile these, and the presence of consistent identifiers will considerably simplify the reconciliation process.

This specification provides two other related methods by which common source derivation can be indicated:

• Provenance - resources that have provenance statements where Provenance.entity.what[x] refers to the same source, and the .entity.role is derivation
• Resource.meta.source - two resources that have the same source

Note that the granularity of Provenance.entity.what[x] / Resource.meta.source is not fixed to a single resource - multiple resources can be derived from a single source entity (e.g. a single CDA document), so applications need to be careful assuming that matching entity source information means that the resources are identifying the same real world concept.