FHIR Reference Resolver & Visualizer

Resolve and visualize FHIR references within a bundle. See dependency graphs and detect broken refs locally.

  • Resolve Reference() targets inside a Bundle and surface broken or dangling links.

How to use the Reference Resolver

  1. Paste a FHIR Bundle (or a single resource) or drop a .json file.
  2. The resolver finds every reference in every entry and lists the relationships between resources.
  3. Select a resource to see its outgoing references (what it points at) and incoming references (what points at it).
  4. Check the unresolved references: references to resources that aren't in the Bundle.

It runs in your browser and doesn't contact any server.

How references are matched

A reference is resolved to an entry in the Bundle when:

  • the reference string equals an entry's fullUrl (this covers urn:uuid: references in transactions and absolute URLs), or
  • the reference is a relative ResourceType/id (such as Patient/123) that matches an entry's resource type and id.

Anything else is reported as unresolved. That's correct for references to resources that live on a server rather than in the Bundle, and a bug for references that were supposed to point inside it.

Worked example

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    { "fullUrl": "urn:uuid:aa11", "resource": { "resourceType": "Patient", "name": [{ "family": "Shaw" }] },
      "request": { "method": "POST", "url": "Patient" } },
    { "fullUrl": "urn:uuid:bb22", "resource": { "resourceType": "Encounter", "status": "finished",
        "class": { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB" },
        "subject": { "reference": "urn:uuid:aa11" } },
      "request": { "method": "POST", "url": "Encounter" } },
    { "fullUrl": "urn:uuid:cc33", "resource": { "resourceType": "Observation", "status": "final",
        "code": { "text": "Heart rate" },
        "subject": { "reference": "urn:uuid:aa11" },
        "encounter": { "reference": "urn:uuid:bb33" } },
      "request": { "method": "POST", "url": "Observation" } }
  ]
}

The Patient has two incoming references. The Observation's encounter reference is unresolved: it says bb33, but the Encounter's fullUrl is bb22. A typo like this is accepted by many servers and produces an Observation attached to no encounter. Finding it before the POST is the point of this tool.

What to look for

  • Unresolved urn:uuid references — always a bug. A urn:uuid only has meaning inside the Bundle.
  • Resources with no incoming references in a transaction — an orphaned Practitioner or Organization that nothing uses may be a mapping mistake.
  • References to the wrong resource type, for example subject pointing at a Practitioner.
  • Relative references in a Bundle whose entries have urn:uuid fullUrls — Patient/123 won't match urn:uuid:..., so these usually point at the server instead.

Working with FHIR References explains every reference form and the official resolution rules.

Limitations

  • Contained resources (#id references) and logical references (by identifier only) aren't resolved.
  • References with a version (Patient/123/_history/2) or an absolute URL are matched only if they equal an entry's fullUrl exactly. The resolver doesn't combine base URLs as the specification's full rules describe.
  • It doesn't check that a reference targets a resource type the element allows. The Resource Inspector shows the allowed targets.

FAQ

Does it fetch referenced resources from my server?

No. It only analyzes what you paste, and nothing leaves your browser.

Which FHIR versions does it support?

R4 and R4B fully, and R5 for ordinary Reference elements. R5's CodeableReference nests the reference one level deeper (medication.reference.reference), and the resolver doesn't detect those yet, so they won't appear in the graph.

What does an unresolved reference mean?

Either the target lives on a server rather than in the Bundle (normal for references like Organization/123 in a searchset), or the reference is wrong. Unresolved urn:uuid references are always errors.

Why doesn't my contained resource resolve?

References starting with # point at resources in the same resource's contained array, which this tool doesn't resolve. See Working with FHIR References.

FHIR Toolbox is a free collection of HL7 FHIR tools by Omindra Labs. The tools process your data in your browser; it is not uploaded for normal tool operations.