Free learning / 50-minute healthcare reference lab

Locate a FHIR reference without changing its identity

Resolve synthetic FHIR R4 Bundle references with server base, UUID, contained scope and exact resource revision intact. Reverse entries to expose an ID-only shortcut and preserve unresolved lookup questions.

Begin reading Download a working copy

No account needed. Use your own copy for writing and keep the original as a reference.

Engineering lab library / Run locally

Choose your next agent lab.

Start with the durable workflow reference, then choose the boundary you want to test. Open its walkthrough for setup, commands and expected observations.

Synthetic records. No provider key or model inference. Runs locally with the standard library.

Start here / Python 3.11+ · Standard library
FHIR reference identity and bounded Bundle lookup
Compare fullUrl, exact history version and contained scope; reverse entries without changing the guarded target.
Python 3.11+ · Standard library · Synthetic FHIR R4 subset · No health records or network
Open walkthrough Download file

Original LockedIn Labs instruction · 50-minute healthcare integration lab · reviewed 28 October 2026.

An Observation names Patient/42. A Bundle contains two Patient resources with ID 42 under different server bases. Which one did it reference? Taking the first matching ID changes the answer when entry order changes. You will reproduce that shortcut, then compare full URLs, resource revisions, UUID references, contained resources and logical identifiers.

FHIR means Fast Healthcare Interoperability Resources. This workshop uses a narrow FHIR R4 collection-Bundle subset and invented Patient/Observation records. It locates data already in those fixtures. It uses Python 3.11+ and the standard library, with no network, database, credentials or real health records. Locating a resource does not verify a person's identity, establish permission or support a clinical, coverage or payment decision.

1. Distinguish the identities in one reference

Term	Meaning in this exercise	Shortcut to avoid
Resource type and id	Patient with local logical ID 42	Treating 42 as globally unique
Server base	The FHIR service context preceding Patient/42	Dropping it because both records have the same ID
Bundle entry fullUrl	Identity used to locate a resource in this Bundle	Assuming array position or display text supplies identity
Resource meta.versionId	An opaque revision of this resource instance	Sorting version labels as numbers or substituting a vocabulary version
Reference.identifier	A logical/business identifier with its own system and value	Treating its value as a FHIR resource id
Contained reference	`#p1` inside its owning resource's context	Resolving it to an unrelated top-level resource with id p1

A resource id, business identifier and real-world person are different concepts. The standard describes references; an enterprise agreement supplies the permitted source, business context and any identity-matching or lookup process. This lab does not implement an identity service or a full FHIR profile validator.

2. Follow the source context before choosing a target

The relative-reference fixture has these three entries:

Identity	Resource	Teaching label
https://synthetic-a.example/fhir/Observation/obs-1	Observation with subject Patient/42	The referring record
https://synthetic-b.example/fhir/Patient/42	Patient id 42	SYNTHETIC-B
https://synthetic-a.example/fhir/Patient/42	Patient id 42	SYNTHETIC-A

The Observation's REST-shaped full URL supplies the relative service base for this collection. The target locator is therefore the synthetic-a Patient URL. The broken matcher keeps only 42 and initially picks SYNTHETIC-B. Its program returns JSON successfully while locating the wrong fixture record.

A fullUrl can instead be a UUID URN, such as urn:uuid:11111111-1111-4111-8111-111111111111. It is matched as a Bundle identity; its final characters are not a resource id. An owner with a UUID URN does not supply this lab's relative HTTP service base. The fixture has no separate transaction/request base from which to infer one.

Six authored visual frames explain the actual Python observations. The browser does not run a source adapter. The written ledger below preserves the same reasoning without requiring the diagram.

UNDERSTAND THE SYSTEM

The resource ID alone does not locate the referenced patient

Six original frames explain actual read-only Python resolution against synthetic FHIR R4 collection Bundles. No health system, identity service or external URL is contacted.

FOLLOW THE WORK

Watch one example, step by step.

6 authored stepsYou control the pace

01 / EXPLORE THE PARTSControls loading · written explanations below

Direction of information or workReturn / feedback

Read the full worked example

01
1 · Two servers share one local id
The Observation belongs to synthetic-a, but the first Patient/42 entry belongs to synthetic-b. The guarded relative locator selects synthetic-a's fullUrl. The ID-only shortcut initially selects B despite successfully producing JSON.
SOURCE CONTEXT: Same resource id 42 · distinct A and B fullUrls
02
2 · Reversing order changes only the shortcut
Reverse the same Bundle entries. The guarded target remains SYNTHETIC-A while its evidence index changes. The broken target becomes A only because it is now the first matching local id. Accidental correctness is not a stable identity contract.
CONTROLLED ENTRY-ORDER CHANGE: Guarded A in both reports · broken B then A
03
3 · A UUID URN is a Bundle identity
The literal UUID URN matches the entry fullUrl even though its Patient resource id is 42. Stripping the URI down to a presumed id misses it. Separately, a UUID owner does not supply this collection's missing HTTP base for a relative Patient/42.
LITERAL FORM AND BASE: Exact UUID match · unavailable relative base stays unresolved
04
4 · Requested history survives URL matching
Patient/42/_history/v2 first locates the versionless fullUrl, then selects exact meta.versionId v2. A versionless reference with v1 and v2 candidates remains ambiguous here; duplicate v2 claims also remain unresolved. The first row is not a latest-version policy.
EXACT RESOURCE REVISION: Requested v2 · no first/last or numeric version guess
05
5 · Containment has an owner
The literal #p1 selects a Patient in the Observation's contained list. A top-level Patient/p1 is not a substitute. The broken global-id comparison selects that unrelated top-level candidate while the guarded result retains the owner.contained path.
CONTAINED SCOPE: Same p1 text · different containing context
06
6 · A logical identifier needs its context
A chart identifier with value 42 is not automatically resource id 42. This fixture returns identifier_lookup_required because no permitted mapping was supplied. An absent local target likewise yields not_in_bundle, without an external fetch or a claim that the person is absent.
BOUNDED UNRESOLVED RESULT: No target fact · specific lookup/coverage question

Read the connections in plain English

01
Referring resource → Literal or logical reference
Retain the actual reference in its owning resource.
02
Literal or logical reference → Bundle identities
Use the supported literal form, base and requested revision.
03
Referring resource → ID-only shortcut
The broken comparison looks only at an apparent final id.
04
ID-only shortcut → Receiving review
A changed first match can expose a wrong fixture target.
05
Literal or logical reference → Unresolved lookup
A logical lookup or unavailable relative base needs an explicit agreement.
06
Bundle identities → Unresolved lookup
Multiple candidate versions or duplicate identities are not guessed away.
07
Bundle identities → Receiving review
Keep the exact entry or contained path beside the target identity.
08
Unresolved lookup → Receiving review
Name the evidence and accountable source/integration owner still needed.

Check your understanding: An ID-only matcher selects the expected Patient after reversing the entries. Has its identity rule been repaired?

No. The original order selected a different server's Patient/42; the reversed order only made its first match accidentally correct. Preserve the owner context, supported fullUrl/contained identity and any requested resource revision, then verify authority separately.

3. Run nine bounded reference cases

← Back to lab library Download FHIR reference identity and bounded Bundle lookup ↓

Download the FHIR reference runner. Predict the target or unresolved reason before each comparison:

Code example

python3 --version
python3 fde-fhir-references.py > references-original.json
python3 fde-fhir-references.py --case relative-two-bases --reverse-entries > references-reversed.json
python3 fde-fhir-references.py --case version-specific > references-versioned.json

The report retains each original Bundle, owner fullUrl, guarded trace and broken ID-only target. entry_index locates an observed target in that particular report; it is an evidence path, not its identity. Reversing entries changes that path without changing the guarded target. No URL is fetched or turned into an external request.

The written ledger

Case	Guarded observation	Why the ID-only shortcut is insufficient
`relative-two-bases`	Locate SYNTHETIC-A by the owner's base and fullUrl	Both servers use Patient id 42; first match initially picks B
`urn`	Locate the exact UUID fullUrl already in the Bundle	The resource id is 42, not the UUID string
`version-specific`	Match the versionless fullUrl and exact meta.versionId v2	Stripping history and taking the first id initially picks v1
`versionless-versions`	Withhold: `ambiguous_bundle_identity`	This fixture contains multiple versions and defines no latest-version choice
`contained`	Locate #p1 only in the owner’s contained list	A top-level Patient/p1 is a different candidate
`logical-only`	Withhold: `identifier_lookup_required`	A chart identifier's value 42 does not become resource id 42
`urn-owner-relative`	Withhold: `relative_base_unavailable`	A plausible Patient/42 elsewhere cannot supply the missing source base
`missing`	Report `not_in_bundle`, with no target	Missing from this fixture does not mean absent from an authoritative server
`duplicate-identity`	Withhold: `ambiguous_bundle_identity`	Two conflicting entries claim the same fullUrl and requested revision

Compare the original and reversed relative-reference reports. The broken target changes from SYNTHETIC-B to SYNTHETIC-A. The guarded resource remains SYNTHETIC-A; only its entry index changes. An accidentally correct first match under one order is not a stable receiving contract.

4. Keep version and lookup gaps unresolved

The version-specific literal is Patient/42/_history/v2. The entry fullUrl stays versionless, and the resource carries meta.versionId v2. The runner removes the history suffix only to locate that fullUrl, then checks the requested revision. It does not discard the version requirement. FHIR fullUrl itself is not a version-specific URL.

A versionless reference with two candidate versions is refused by this exercise's conservative policy. Revision strings are opaque. Choosing the lexically largest label or last network arrival is not an implemented latest-version agreement. A duplicated fullUrl plus revision remains ambiguous even if one candidate looks more useful to the application.

For a logical-only reference, HL7 permits context-dependent identifier resolution. This lab deliberately requires a separately agreed lookup and returns identifierlookuprequired. It does not claim logical references are invalid FHIR, or that FHIR prohibits inspecting identifiers within a Bundle. The fixture has no authoritative business-identifier mapping or permitted source lookup.

The resolver supports only the stated collection, Patient-subject and literal forms. Unsupported forms remain unresolved. A refusal is not a general FHIR validation verdict. The same applies to notinbundle: any actual source read would need a trusted allowlist, authorization, profile/freshness policy, response bounds and receiving ownership. Never follow arbitrary supplied URLs just to make the unresolved state disappear.

5. Receive the reference contract as a healthcare pod

Use integration builder, source/terminology steward and receiving engineer roles. Combine roles explicitly for small groups; label solo work self-review. Each person keeps their own predictions, evidence and help received. The receiver chooses entry reversal or a requested revision and asks the builder to locate its target and unresolved boundary without taking over their navigation.

Role	Receiving responsibility
Integration builder	Preserve the referring resource, literal form, base/fullUrl, requested revision and exact observed evidence path
Source/identity steward	Establish permitted server and business-identifier context; define ambiguity and lookup policies
Receiving engineer	Reproduce one stable target and one withheld case, then return the specific missing evidence and next owner
Security/platform owner	Verify actual source authentication, URL restrictions, workspace permissions, limits and freshness before deployment

Text example

My role / exact command and report:
Prediction before resolving the reference:
Referring fullUrl / original Reference field:
Derived locator / requested resource revision:
Observed entry path or contained path / exact target:
One changed condition / prediction before that run:
New observation kept separately:
Receiving action actually attempted / assistance:
Unresolved lookup or authority / next accountable role and bounded action:

The result state is locatedinfixture, not patientverified or readyfor_care. Do not use real patient records in this exercise. Completing it does not establish independent review, qualification, client placement or authority to access a health system. Carry the identity evidence into the existing versioned-handoff contract rather than treating a located record as a supported eligibility fact.

6. Defend the boundary in an interview

Why is Patient/42 insufficient without context? When can a UUID reference be located locally? Why must a requested history revision survive URL matching? Why does a contained id have a different scope? What evidence is still needed for a business-identifier lookup? Explain using particular fixture rows.

Primary FHIR R4 sources checked 28 October 2026:

The resolver policy, counterexamples and role exercise are original LockedIn Labs instruction. Continue to the versioned healthcare handoff and its protected Academy lesson with existing training access.