Reference Integrity in a Distributed FHIR Deployment

Reference integrity in a single-node FHIR server is a solved problem. Reference integrity across multiple servers, replicas, or federated stores is where the interesting failure modes live. The spec deliberately does not enforce referential integrity — the server may allow a reference to a resource that does not exist. That flexibility is a feature and a hazard, and the way each deployment handles it decides a lot of downstream behavior. The site's Bundle reference walker surfaces broken references at inspection time. For the wider FHIR framing, deeper analytics and AI on FHIR coverage has more.

The Spec Position

FHIR does not require the referenced resource to exist. A Patient can be referenced from a hundred Observations before the Patient is created, and none of the Observation writes will fail on the reference alone. That behavior enables real workflows — a client that receives an Encounter first and the Patient second is common in practice.

The consequence: reference integrity is a deployment choice, not a spec guarantee. The deployment picks the strictness, and the resolver has to reflect it.

Enforcement Levels

None — the server accepts references to anything, valid or not
Referential — the server checks that the target exists at write time
Strict Referential — the server also checks target type matches the declared reference type
Cascading — the server manages updates to referenced resources on the target changing

Most production servers pick "None" for flexibility and let the client enforce integrity where it matters. That is a design choice worth understanding rather than fighting.

Federated Deployments Amplify the Question

When one FHIR server holds Patients and another holds Observations, references cross the boundary. The Observation server has no visibility into the Patient server's state. A Patient referenced from an Observation may not exist at all, or may exist with different identifiers, or may exist at multiple sites simultaneously.

The resolver in a federated context has to know where each resource type lives, dispatch reads accordingly, and handle "not found" as a real outcome. For the design that survives that, designing a reference resolver that survives partial outages covers the mechanics.

Reference by Identifier As a Signal

Reference.identifier (as opposed to Reference.reference) is the FHIR mechanism for "we know the identity but not the URL". It carries a system + value pair and lets the resolver look up the target via search rather than by direct GET.

Identifier-based references are common in federated deployments — they insulate the sender from knowing the target's URL structure. The trade: the resolver has to do a search rather than a lookup, and the search may return zero, one, or many hits.

Version-Specific References Are a Different Kind of Integrity

A reference to Patient/123/_history/5 refers to a specific version. Referential integrity for versioned references requires the target server to preserve history. If history is truncated or purged, the reference becomes unresolvable in a specific and detectable way. For the mechanic, version-specific references: when you need them, when you don't is the entry.

Repair Strategies

Detect at ingest — the resolver flags unresolvable references as it walks
Repair at read — the resolver retries later, in case the target has since appeared
Escalate to human — for references that stay broken past a threshold, log for review

Different workflows pick different mixes. The right rule is: the workflow that reads the reference is the one that has to know it might not resolve.

The Short Version

FHIR does not enforce integrity — deployments do. Federation amplifies the question. Identifier references buy insulation. Version-specific references require history. Repair strategies matter as much as detection strategies. For the base pattern, resolving FHIR references without a full database walk is the entry.