Bundle

fhir technical technical fhirinteroperability
Source: HL7 Reviewed: 17/12/2025 License: CC-BY-4.0

Bundle

A Bundle is a FHIR resource that acts as a container for a collection of resources. Bundles are fundamental to FHIR’s RESTful architecture, enabling multiple resources to be transmitted, processed, or stored together as a single unit.

Bundle Types

FHIR defines several bundle types, each with specific use cases:

Document Bundle

Contains a Composition resource and all referenced resources, representing a clinical document.

{
  "resourceType": "Bundle",
  "type": "document",
  "entry": [
    {
      "fullUrl": "http://example.org/Composition/123",
      "resource": {
        "resourceType": "Composition",
        ...
      }
    }
  ]
}

Transaction Bundle

Executes multiple operations atomically - either all succeed or all fail.

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "request": {
        "method": "POST",
        "url": "Patient"
      },
      "resource": {
        "resourceType": "Patient",
        ...
      }
    }
  ]
}

Batch Bundle

Executes multiple independent operations - each can succeed or fail independently.

Search Results Bundle (searchset)

Returned from search operations, contains matching resources.

History Bundle

Contains previous versions of a resource.

Collection Bundle

Simple grouping of resources for convenience.

Message Bundle

Contains a MessageHeader and related resources for FHIR messaging.

Version Differences

FHIR R5

  • Enhanced support for subscription notifications in Bundle
  • Improved batch/transaction processing rules
  • Better error handling specifications

FHIR R4

  • Stable bundle type definitions
  • Normative status for core bundle functionality
  • Well-defined transaction/batch semantics

STU3 and Earlier

  • Simpler bundle structure
  • Fewer bundle types available
  • Less sophisticated transaction handling

Common Use Cases

  1. Bulk Data Transfer: Group resources for efficient transmission
  2. Atomic Transactions: Create patient with related observations in single request
  3. Clinical Documents: Package CDA-like documents in FHIR format
  4. Search Results: Return multiple matching resources from queries
  5. Messaging: Wrap messages with routing and metadata

Technical Considerations

Performance

  • Large bundles can impact server performance
  • Consider pagination for search results
  • Use batch operations carefully

Security

  • Bundle entries may have different access controls
  • Verify permissions for each resource in bundle
  • Transaction bundles require careful authorization

Error Handling

  • Transaction bundles: single error fails entire bundle
  • Batch bundles: errors returned per entry
  • Always check bundle response for operation outcomes
  • Resource: Individual FHIR data objects contained in bundles
  • Transaction: Atomic bundle type ensuring all-or-nothing execution
  • Batch: Non-atomic bundle type for independent operations
  • Composition: Document-style resource often used in document bundles
  • MessageHeader: Required first entry in message-type bundles

References