FHIR R4 gives two ways to connect one resource to another. Reference points at a resource by URL or logical id. Contained embeds a full resource inside the parent. Both are valid, and choosing between them is a small design decision with a large downstream effect. The site's R4 resource atlas marks each element's reference type explicitly. For the wider FHIR framing, the FHIR comparison index has related pieces.
Reference: The Default
A Reference points at another resource by:
- Relative URL
Patient/123 - Absolute URL
https://server.example.org/Patient/123 - Logical identifier via
Reference.identifierwhen the id is unknown - URN in a transaction Bundle via
urn:uuid:...
Reference is the default because it preserves resource identity, keeps payloads small, and lets the referenced resource live and change on its own. A Practitioner referenced from a hundred Observations is one Practitioner, not a hundred copies. That is the interoperability model FHIR is built around.
Contained: The Escape Hatch
Contained embeds a full resource inside the parent's contained array. The contained resource has no independent existence — it lives only inside its parent. Use contained when:
- The child has no identity outside the parent context
- The child is generated on the fly and not persisted independently
- The receiver has no meaningful way to look up the child by id
A Medication resource contained inside a MedicationRequest is a common example, when the medication is a one-off compound with no independent catalog entry.
Do Not Contain Reusable Entities
Patients, Practitioners, and Organizations should almost never be contained. They have identity, they get referenced from many places, and containing them fragments that identity across parent resources. A Patient contained inside an Encounter is the same person as the Patient contained inside a different Encounter — but from the FHIR resource-identity perspective, they are two distinct records. That is a data-quality problem waiting to bite.
The Reference Type Contract
Every Reference element declares which resource types it accepts. Observation.subject accepts Patient, Group, Device, or Location. Sending a Reference to Practitioner in Observation.subject fails validation. That declaration is on the resource definition, and clients that ignore it end up with payloads that pass smoke tests but fail on a strict validator. For the way to read those declarations, reading a FHIR resource definition the way developers read a class covers the mechanic.
Reference.identifier: The Fallback
When the server does not know the logical id of the referenced resource yet, use Reference.identifier instead of Reference.reference. That fallback is what allows a client to send an Encounter with an external MRN before the Patient has been created on this server. It is expected, common, and often overlooked.
The Transaction Bundle Twist
Inside a transaction Bundle, references between entries can use urn:uuid:.... The server rewrites those URNs to real ids atomically at commit. That trick only works in transactions, not in batches, and it is how a client sends coupled entries without a prior create round-trip.
What This Buys You
Choosing Reference over contained keeps the resource graph clean, preserves identity, and lets receivers look up related resources on their own schedule. Choosing contained keeps the payload self-contained when the child has no external identity. Both have their place. The atlas surfaces the reference type per element to make the check fast.
For the base pattern, navigating FHIR R4 resources when you know DomainResource but not much else is the entry. For the ten resources you meet most, the ten FHIR resources you should learn first covers them.
Sources
- HL7 canonical R4 references chapter covering Reference and - HL7 canonical R4 references chapter covering Reference and contained
