Version-Specific References: When You Need Them, When You Don't

A FHIR reference can point at a specific version of a resource by appending _history/N to the URL. That version-specific form solves a real problem — capturing what a decision was made against — and creates a real cost, since the target server has to preserve the history for the reference to stay resolvable. Knowing when to reach for it and when not to is the payoff-heavy call. The site's Bundle reference walker surfaces version-specific references distinctly. For the wider FHIR framing, related FHIR infrastructure guides has more.

What Version-Specific Looks Like

Patient/123 — the current version, whatever it is when you resolve
Patient/123/_history/5 — version 5 specifically, regardless of what the current version is

Everything from Patient to Observation supports the same shape. The _history/N suffix picks the version; the resolver has to preserve it.

When You Need Version-Specific

Reach for it when the payload is asserting "this decision was made against this specific state of the resource." Common cases:

A signed prescription that must record the medication state at signing
An audit event that references the exact state the user was viewing
A DocumentReference that captures a snapshot at publication
A Provenance record that ties an action to a specific version of the target
A regulatory submission that must survive future edits to the source

In each case, the value of the reference is that it does not silently shift when the target changes.

When You Don't

Skip it when you want the reference to follow the target's current state. Common cases:

Encounter references from Observations — the Encounter's current state is what matters
Practitioner references from most resources — the current practitioner record is fine
Organization references — same, current record follows edits naturally

If the reference is a foreign key to identity rather than to state, do not pin the version.

What Preservation Requires

For a version-specific reference to resolve, the target server has to keep the history. Servers vary — some keep unlimited history, some purge after a retention window, some let the operator configure per-resource-type. A version-specific reference to a resource whose history has been purged returns 404 with a specific enough message that a well-written resolver can distinguish.

For the deployment-wide picture, reference integrity in a distributed FHIR deployment covers what happens across servers.

Cycles Are Still Possible

Version-specific references can still cycle. A reference in version 3 of resource A that points at version 2 of resource B, which itself references version 5 of resource A, and so on. The resolver has to detect. For the detection pattern, circular references and how to detect them safely is the entry.

Storage Cost

Every version-specific reference is an implicit request to the target server: "keep this version resolvable forever, or until my reference dies." That is a real operational cost. Deployments that treat every reference as version-specific are inflating storage in a way that surfaces as retention pressure years later.

Reserve version-specific for the cases where the immutability matters. Use current-version references for the rest.

The Resolver Behavior

A resolver that receives a version-specific reference has to preserve the suffix through resolution. Rewriting Patient/123/_history/5 to Patient/123 on lookup loses the semantic. For the design pattern that preserves shape, designing a reference resolver that survives partial outages covers the mechanics.

The Short Version

Use version-specific when the reference asserts a decision against a fixed state. Skip it for identity references. Preservation is the target server's cost. Detect cycles. The resolver has to keep the version suffix through the walk.