This page is part of the Continuous Integration Build of FHIR Specification (v4.0.1: R4 - Mixed Normative and STU ) in it's permanent home (it will always (will be available incorrect/inconsistent at this URL). The current version which supercedes this version is 5.0.0 . For a full list of available versions, see times).
See the Directory of published versions . Page versions: R5 R4B R4 R3 R2

• Content
• Examples Detailed Descriptions
• Detailed Descriptions Search Params
• Mappings
• Examples
• Operations
• Profiles & Extensions
• R3 Conversions Extensions

2.36 2.4 Resource Bundle - Content

Responsible Owner: FHIR Infrastructure Work Group

Maturity Level : N   Normative (from v4.0.0)

Security Category : Not Classified

Compartments : Not linked to any No defined compartments

This page has been approved as part of an ANSI standard. See the Infrastructure Package for further details.

A container for a collection of resources.

2.4.3 References to this Resource

• Resource References: Procedure

2.36.3 2.4.4 Resource Content

 

See the Profiles & Extensions and the alternate Additional definitions: Master Definition XML + JSON , XML Schema / Schematron + JSON Schema , ShEx (for Turtle ) , the spreadsheet version & the dependency analysis

2.36.3.1 2.4.4.1 Terminology Bindings

Path	Definition ValueSet	Type	Reference Documentation
Bundle.type	BundleType	Required	Indicates the purpose of a bundle - how it is intended to be used.
Bundle.link.relation	LinkRelationTypes	Required	BundleType Link Relation Types defined at https://www.iana.org/assignments/link-relations/link-relations.xhtml#link-relations-1
Bundle.entry.search.mode	SearchEntryMode	Required	Why an entry is in the result set - whether it's included as a match or because of an _include requirement, or to convey information or warning information about the search process.
Bundle.entry.request.method	HTTPVerb	Required	SearchEntryMode Bundle.entry.request.method HTTP verbs (in the HTTP command line). See [HTTP rfc](https://tools.ietf.org/html/rfc7231) for details. Required HTTP rfc HTTPVerb for details.

2.36.3.2 2.4.4.2 Constraints

2.36.3.3 2.4.4.3 Notes about Bundle

• Conceptually, a bundle is a list of resources with some context (named links, and status on the entries)
• Since a Bundle is itself a Resource it has the same common metadata as all resources, including profile assertions, tags, and security labels labels. Note that the values in Bundle.meta.security will generally be influenced by the meta.security values of the entries within the Bundle; see http://hl7.org/fhir/security.html
• Although there are no extensions on the Bundle itself, link , entry , and search / request / response can all have extensions. See Patient and Location for examples on search
• Both Bundle.link and Bundle.entry.link are defined to support providing additional context when Bundles are used (e.g. HATEOAS ). Bundle.entry.link corresponds to links found in the HTTP header if the resource in the entry was read directly. This specification defines some specific uses of Bundle.link for searching and paging , but no specific uses for Bundle.entry.link, and no defined function in a transaction - meaning is implementation specific
• Bundles have both .id and .identifier - see Resource Identities for further information

2.4.4.4 Using Additional Resources in Bundles

Bundle entries contain resources which may be either be one of the 134 resources defined in this specification, or an additional resource .

In JSON, this looks like:

{
  "resourceType" : "Bundle",
  "entry" : [{
    "resource" : {
      "resourceType" : "ViewDefinition",
      "resourceDefinition" : "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/ViewDefinition|2.0.0-pre",
      "id": "a-valid-id",
      // etc
    }
  }]
}

In XML, this looks like:

<Bundle xmlns="http://hl7.org/fhir">
  <entry> 
    <resource> 
      <ViewDefinition xmlns="http://hl7.org/fhir" 
        resourceDefinition="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/ViewDefinition|2.0.0-pre">
        

        // etc
      <ViewDefinition>
    </resource> 
  </entry> 
</Bundle> 

See general note to balloters about Additional resources

2.36.3.4 2.4.4.5 Using Bundles

The content and rules for using a Bundle depend on the type of the bundle. Note that all bundle types use resource identity resolution as described below.

2.36.3.4.1 2.4.4.5.1 Document

A document Bundle (type = "document") consists of a series of entries, the first of which is a Composition . Each entry element SHALL contain contains a resource. See Documents for further information.

Example

2.36.3.4.2 2.4.4.5.2 Message

A message Bundle (type = "message") consists of a series of entries, the first of which is a MessageHeader . Each entry element SHALL contain contains a resource. See Messaging for further information.

Example Request and Response

2.36.3.4.3 2.4.4.5.3 Search Results

A set of search results (type = "searchset") consists of a series of 0 or more entries. Each entry element SHALL contain contains a resource. See Search for further information.

In addition, Bundle.total may be used to return the total number of resources that match the search, and that may be returned by following the "next" link . This total MAY be an estimate. Full iteration of the search set or using _total=accurate are the only mechanisms to reliably determine an exact count against an arbitrary system.

For each entry, a search set can also contain two specific pieces of search related information:

• search.mode : An indication of whether the resource is in the search set because it matched the search criteria or whether it is included because another resource refers to it (e.g. by the _include parameter)
• search.score : The server's search ranking score for the entry. Servers are not required to return a ranking score, but if they do, 1 is most relevant, and 0 is least relevant. Note: often, search results are sorted by score, but the client may specify a different sort order (see Search Relevance )

Example

2.36.3.4.4 2.4.4.5.4 History

A change history (type = "history") consists of a series of 0 or more entries. Each entry element SHALL contain a request element that describes the change that was made and, if the method is a POST POST, PATCH, or PUT, a resource that represents the state of the resource at the conclusion of the operation. A response element SHALL also be present so that consumers can access the location header. See History for further information.

In addition, Bundle.total may be used to return the total number of resources that are included in the change history, including those that may be returned by following the "next" link .

2.36.3.4.5 2.4.4.5.5 Transaction / Batch

A transaction (type = "transaction") or batch (type = "batch") consists of a series of 0 or more entries. Each entry element SHALL contain contains a request element has the details of an HTTP operation that informs the system processing the transaction what to do with the entry. If the entry method is a 'PUT' 'PUT', 'PATCH' or 'POST', then the entry SHALL contain contains a resource that becomes the body of the HTTP operation. See Transactions for further information.

Example

2.36.3.4.6 2.4.4.5.6 Transaction/Batch Response

A transaction response (type = "transaction-response") or batch response (type="batch-response") consists of a series of 0 or more entries: 1 for each entry in the transaction or batch it is in response to. Each entry element SHALL contain contains a response element which indicates the outcome of the HTTP operation that the server performed for the entry.

Example

2.36.3.4.7 2.4.4.5.7 Collection

A collection (type = "collection") consists of a series of 0 or more entries. No particular use with respect to the FHIR specification is associated with this Bundle. Each entry element SHALL contain contains a resource.

Example

2.4.4.5.8 Subscription Notification

Normative Candidate Note: This BundleType is not normative - it is still undergoing Trial Use while more experience is gathered.

A subscription notification (type = "subscription-notification") consists of a series of 1 or more entries, the first of which is a SubscriptionStatus . There may be additional contents, as specified by the subscription responsible for generating the notification. See Subscription for further information.

Examples

2.36.4 2.4.5 Resource URL & Uniqueness rules in a bundle

Except for transactions and batches, each entry in a Bundle must SHALL have a fullUrl which is the identity of the resource in the entry. Note that this is not a versioned reference to the resource, but its identity. Where a resource is not assigned a persistent identity that can be used in the Bundle, a UUID should SHALL be used in fullUrl (urn:uuid:...).

For transactions and batches, entries MAY not have omit fullURLs when the entry.request.method = POST, and the resource has no identity. Note that even in this case, there may still be a fullURL in a transaction on a when entry.request.method = POST so that relationships between resources can be represented (see Transactions ).

A given version of a resource SHALL only appear once in each Bundle. There might, MAY, however, be multiple versions of a single resource present in a single bundle. This would be expected in Bundles of type history , and also might be necessitated by closely tracking Provenance.

Note that the meaning of an unversioned reference to a resource that appears multiple times is potentially ambiguous, though processors may have additional informaton information to help resolve this (e.g. change order in a history bundle).

When processing batches and transactions, it is at server discretion how to behave if multiple versions of a single resource are present.

2.36.4.1 2.4.5.1 Resolving references in Bundles

The Bundle resource is a packaging construct that has one of more entries that are other kinds of resources. Those resources themselves have references to other resources - e.g. an Observation that refers to a Patient. The referenced resources may also be found in the Bundle. For example, the system that constructed the Bundle may have included both the Observation and the Patient. The content of the references between resources doesn't change because of the bundle.

This section documents a method that resolves references correctly within a bundle. Note that this method does not define any new semantics; resolution is based on the way resource identity and resource references work.

Applications reading a Bundle should always look for a resource by its identity in the bundle first before trying to access it by its URL externally.

Note that reference.reference in entry resources can use any URI scheme (in addition to using relative values like "Patient/123").

How to resolve a reference in a Bundle:

Resolving urns. If the reference.reference is a URN (always absolute) (e.g. "urn:uuid:9d1714da-b7e6-455b-bfd2-69ce0ff5fb12")

• Look for an entry with a fullUrl that matches the reference.reference
• If one is found, the resolution succeeds (and ends) here
• Otherwise, the resolution fails (and ends) here. The reference is not an has no defined meaning within this specification.

Resolving absolute reference, convert it to references. If the reference.reference is an absolute URL: URL (e.g., "https://fhir.example.org/base/Patient/123", "https://fhir.example.org/base/Patient/123/_history/a"):

• if If the reference reference.reference is versionless (i.e. it has no "/_history/" path segment - e.g. "https://fhir.example.org/base/Patient/123"):
  • Look for an entry with a fullUrl that matches the format [type]/[id], and reference.reference
  • if If one is found, the fullUrl for resolution succeeds (and ends) here
  • If more than one is found, the bundle entry containing server MAY look for the resource most recent version (based on meta.lastUpdated). If it is a RESTful able to find exactly one (see most recent this way, the RESTful URL regex ) resolution succeeds (and ends) here
• extract If the [root] from reference.reference includes a "_history" path segment (e.g. "https://fhir.example.org/base/Patient/123/_history/a"), split the fullUrl, value into two parts: a versionless reference (e.g. "https://fhir.example.org/base/Patient/123" and append a version id (e.g. "a")
  • Look for an entry with a fullUrl that matches the versionless reference (type/id) to and a resource.meta.versionId that matches the reference's version id.
  • If a single record is found, the resolution succeeds (and ends) here.
  • If multiple records are found, it is an error.
• then try Optionally, attempt to resolve within the bundle as for URI if possible (e.g. by issuing a RESTful FHIR [read] on an https URL reference. if not version-specific or a [vread] it the URL is version-specific).
  • If no found, the resolution is possible, then succeeds (and ends) here.
  • Otherwise, the resolution fails (and ends) here. The reference has no defined meaning within this specification specification.
else no resolution

Resolving relative references against a RESTful base. If the reference.reference is possible and of the form "[type]/[id]" (e.g., "Patient/123"):

• If the Bundle entry containing the reference has no defined meaning within this specification a fullUrl matching the RESTful URL regex (e.g., "https://fhir.example.org/Observation/456"):
  • Extract the [root] from the Bundle entry's fullUrl and append the relative reference to it (e.g., "https://fhir.example.org/" + "Patient/123" --> "https://fhir.example.org/Patient/123")
  • Follow the steps for Resolving absolute references above
• else Look for an If the Bundle entry with containing the reference does not have a fullUrl that matches the URI in [RESTful URL regex] and the reference if no match Bundle is found, a batch or transaction and the URI entry.request.method is a POST, PUT or PATCH
  • take the base URL of the server that can be resolved (e.g. if an http: URL), try accessing is the target of the batch/transaction and append the relative reference to it directly) (e.g., transaction is being posted to "https://fhir.somewhere.org", then the expanded reference would be "https://fhir.somewhere.org/Patient/123"
  • Follow the steps for Resolving absolute references above

Note, Resolving conditional references. If the reference occurs in addition, that a reference may be by identifier, and if it is, transaction Bundle and there the reference.reference is no URL, it may a conditional reference (e.g. "http://example.org/base/Patient?identifier=1234"):

• Logically perform all creates, updates and deletes as defined in the Bundle. (If this involves physically performing the creates, logical references will need to be resolved by scanning removed or, potentially based on cardinality or business rules, replaced with a valid temporary reference.) Perform the ids [search] specified in the bundle. Note also that transactions may contain conditional reference on the server.
  • If the search succeeds with a single resource, the resolution succeeds (and ends) here.
  • If the search succeeds with multiple matching resources, resolution fails (and ends) here. An error SHOULD be raised.
• Otherwise the resolution fails (and ends) here.

NOTE: It is sometimes not safe to perform resolution of conditional references that must within the Bundle because in some cases there may be resolved by multiple matches which, once the server before processing data hits the matches. server, will turn into a single match due to mutually exclusive conditional create/conditional update rules.

Resolving canonical references: If the canonical reference is version specific (either relative or absolute), then remove the version from the version-specific, look for an entry with a matching URL before and version. If the canonical omits version, look for an entry with a matching fullUrl, URL and then match if there is more than one, find the most recent version based on Resource.meta.versionId . the versionAlgorithm. If there is exactly one, it's a match. If there are no matches, then resolve as an external canonical as usual. If there is more than one, it's an error.

Resolving other references. If the rules above do not apply, the resolution fails (and ends) here. The reference has no defined meaning within this specification.

Note that the rules for resolving references in contained resources are the same as those for resolving resources references in the resource that contains the contained resource. I.e. the fullUrl of the containing resource is used when determining the base for relative references, etc.

Several portions of this algorithm are dependent on on the presence of Bundle.entry.fullUrl. In instances where references might be resolved within a Bundle but entries do not have fullURLs, resolution expectations are undefined. For this reason, Bundles where cross-Bundle references are present SHOULD always populate Bundle.entry.fullUrl.

If multiple matches are found, found (except where explicitly handled in the above algorithm), it is ambiguous which is correct. Applications MAY return an error or take some other action as they deem appropriate. appropriate

There is an example Bundle that demonstrates these rules.

2.4.5.2 Graph-connected Bundles

Both FHIR messages and FHIR documents have a requirement that all entries within the Bundle are interconnected. This expectation means that all entries in the Bundle must produce a single graph of interconnected resources. These connections might be via Reference, canonical, url, or "href" references within narrative.

Note that some references might be 'reverse' references, such as Provenances that point to resources within the Bundle. These references are resolved as defined above.

2.36.4.2 2.4.5.3 Serving Bundles using the RESTful API

The Bundle resource type has an end-point like all most other resources. This end-point serves the usual interactions . Bundles are treated as static resources on the /Bundle end-point (i.e. when a batch, transaction, or message is POSTed to /Bundle, it is stored as is, and the content is not processed as batch, transaction, or message - instead, they are processed like normal resource, with indexing / auditing etc. Performing a GET /Bundle/[location] /[base]/Bundle/[location] will return the same resource.

The Bundle end point does have two special search parameters - composition and message , which allow for chained search into the first (special) entries in document and message resources.

All elements in Bundle are marked as summary because Bundle resources need to be fully populated when doing a search, and most use cases for retrieving summaries of documents or other types of bundles are not well suited by the standard isSummary mechanism and are better handles by operations or other mechanisms.

Note to Implementers: If an element marked as 'summary' is itself a nested resource (i.e. type is Resource), then the expectation is that the conveyed resource will also be expressed in its summary form. The typical place this applies is Bundle.entry.resource. This statement is left as STU because there is not yet significant implementer experience on its ramifications.

2.4.5.4 Signatures

The Bundle resource includes a signature element (digital signature) which can be used for standards based integrity verification and non-repudiation purposes. The Signature datatype provides details on use of the signature element. The Signature.type coded value of "Source" should be used when the signature is for simply proving that the resource content is the same as it was when the resource was updated or created.

2.36.5 2.4.6 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource , and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Expression	In Common
composition TU	reference resource	The first resource in the bundle, if the bundle type is "document" - this is a composition, and this parameter provides access to search its contents	Bundle.entry[0].resource ( as Composition )
identifier TU	token	Persistent identifier for the bundle	Bundle.identifier
message TU	reference resource	The first resource in the bundle, if the bundle type is "message" - this is a message header, and this parameter provides access to search its contents	Bundle.entry[0].resource ( as MessageHeader )
timestamp TU	date	When the bundle was assembled	Bundle.timestamp
type TU	token	document | message | transaction | transaction-response | batch | batch-response | history | searchset | collection | subscription-notification	Bundle.type