FHIR Bundles

A Bundle is a FHIR resource that groups other resources together for transport. Bundles are conceptually similar to HL7 v2 batch messages (BHS/BTS) but with explicit semantics about how the server should process the contents.

Structure

Every Bundle has:

• resourceType: "Bundle"
• type: one of the values in the table below.
• entry: an array of entries. Each entry has an optional fullUrl, a resource, and (for transaction/batch/searchset/history) some entry-specific metadata.

Bundle types

Type	Purpose	Server behavior
document	A persistent clinical document, for example a discharge summary. The first entry is a Composition.	Stored as a unit; signed by the source.
message	An event-driven push, with the routing details in a MessageHeader entry (similar to an HL7 v2 BHS/BTS).	Server reacts to the event named in MessageHeader.event.
transaction	A set of REST operations applied atomically.	All entries succeed or all are rolled back. Order of execution is preserved.
batch	A set of independent REST operations.	Each entry is processed separately; some can succeed and others fail. Execution order is not guaranteed.
history	The version history of a resource.	Returned by the server for GET /[Resource]/_history.
searchset	The result of a search query.	Returned by the server for any GET /[Resource]?... query.

Transaction vs. batch, which to use

The difference matters when more than one resource depends on another:

• Pick transaction when the entries refer to each other (a Patient and a related Observation, for example) and partial failure would leave the data inconsistent. The server resolves intra-Bundle references and either commits all entries or none.
• Pick batch when the entries are independent and partial success is acceptable. Batches typically run faster because the server can process entries in parallel.

reference vs. fullUrl

The two terms look similar but serve different roles.

reference is an element inside a resource that points to another resource. It accepts three forms:

"subject": { "reference": "Patient/1234" }                                          // relative — same server
"subject": { "reference": "https://fhir.example.com/Patient/1234" }                 // absolute — external server
"subject": { "reference": "urn:uuid:550e8400-e29b-41d4-a716-446655440000" }         // UUID — used inside a Bundle before IDs are assigned

fullUrl is a property on a Bundle entry that uniquely identifies that entry within the Bundle. It is what other entries' reference values resolve against during transaction processing. When the server commits the Bundle, it replaces UUID fullUrls with permanent resource URLs and rewrites the corresponding reference values to match.

A typical transaction Bundle that creates a Patient and an Observation that refers to that Patient:

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:9b6f3c1e-1d4a-4d4c-9a4d-7e0f4a6c3d2b",
      "resource": {
        "resourceType": "Patient",
        "name": [{ "family": "Smith", "given": ["Alice"] }]
      },
      "request": { "method": "POST", "url": "Patient" }
    },
    {
      "fullUrl": "urn:uuid:1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "resource": {
        "resourceType": "Observation",
        "status": "final",
        "code": { "text": "Body temperature" },
        "subject": { "reference": "urn:uuid:9b6f3c1e-1d4a-4d4c-9a4d-7e0f4a6c3d2b" },
        "valueQuantity": { "value": 98.6, "unit": "degF" }
      },
      "request": { "method": "POST", "url": "Observation" }
    }
  ]
}

After the server commits the Bundle, the response Bundle's entries carry the assigned location URLs (for example Patient/4321 and Observation/8765), and the Observation's subject.reference is rewritten to Patient/4321.