This page is part of the FHIR Specification (v3.0.2: STU 3). The current version which supercedes this version is 4.0.1 . For a full list of available versions, see the Directory of published versions

• Content
• Examples
• Detailed Descriptions
• Mappings
• Profiles & Extensions
• R2 R3 Conversions

2.36 2.37 Resource Bundle - Content

FHIR Infrastructure Work Group

Maturity Level : 5 N

Trial Use Normative (from v4.0.0)

Security Category : Not Classified

Compartments : Not linked to any 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.37.3 References

No resources refer to this resource directly.

This resource does not implement any patterns.

2.36.3 2.37.4 Resource Content

 

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

2.36.3.1 2.37.4.1 Terminology Bindings

Path	Definition	Type	Reference
Bundle.type	Indicates the purpose of a bundle - how it was is intended to be used.	Required	BundleType
Bundle.entry.search.mode	Why an entry is in the result set - whether it's included as a match or because of an _include requirement. requirement, or to convey information or warning information about the search process.	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	HTTPVerb

2.36.3.2 2.37.4.2 Constraints

id	Level	Location	Description	Expression
bdl-1 :	Rule	(base)	total only when a search or history ( expression	: total.empty() or (type = 'searchset') or (type = 'history') )
bdl-2 :	Rule	(base)	entry.search only when a search ( expression	: entry.search.empty() or (type = 'searchset') )
bdl-3 :	Rule	(base)	entry.request only mandatory for some types of bundles ( expression batch/transaction/history, allowed for subscription-notification, otherwise prohibited	: entry.request.empty() or type entry.all(request.exists() = (%resource.type = 'batch' or type %resource.type = 'transaction' or type %resource.type = 'history' 'history')) or (type='subscription-notification') )
bdl-4 :	Rule	(base)	entry.response only mandatory for some types of bundles ( expression batch-response/transaction-response/history, allowed for subscription-notification, otherwise prohibited	: entry.response.empty() or type entry.all(response.exists() = (%resource.type = 'batch-response' or type %resource.type = 'transaction-response' or %resource.type = 'history')) or (type='subscription-notification') )
bdl-5 : On Bundle.entry:	Rule	Bundle.entry	must be a resource unless there's a request or response ( expression	on Bundle.entry: resource.exists() or request.exists() or response.exists() )
bdl-7 :	Rule	(base)	FullUrl must be unique in a bundle, or else entries with the same fullUrl must have different meta.versionId ( expression (except in history bundles)	: entry.where(fullUrl).select(fullUrl&resource.meta.versionId).isDistinct() (type = 'history') or entry.where(fullUrl.exists()).select(fullUrl&resource.meta.versionId).isDistinct() )
bdl-8 : On Bundle.entry:	Rule	Bundle.entry	fullUrl cannot be a version specific reference ( expression	on Bundle.entry: fullUrl.contains('/_history/').not() )
bdl-9 :	Rule	(base)	A document must have an identifier with a system and a value ( expression	: type = 'document' implies (identifier.system.exists() and identifier.value.exists()) ) 2.36.3.3
bdl-10	Rule	(base)	A document must have a date	type = 'document' implies (meta.lastUpdated.hasValue())
bdl-11	Rule	(base)	A document must have a Composition as the first resource	type = 'document' implies entry.first().resource.is(Composition)
bdl-12	Rule	(base)	A message must have a MessageHeader as the first resource	type = 'message' implies entry.first().resource.is(MessageHeader)
bdl-13	Rule	(base)	A subscription-notification must have a SubscriptionStatus as the first resource	type = 'subscription-notification' implies entry.first().resource.is(SubscriptionStatus)

2.37.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
• 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 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.36.3.4 2.37.4.4 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.37.4.4.1 Document

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

Example

2.36.3.4.2 2.37.4.4.2 Message

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

Example Request and Response

2.36.3.4.3 2.37.4.4.3 Search Results

A set of search results (type = "searchset") consists of a series of 0 or more entries. Each entry element SHALL contain 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 .

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, 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.37.4.4.4 History

An 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, made and, if the method is a POST 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, and including those that may be returned by following the "next" link .

4 Example to do

2.36.3.4.5 2.37.4.4.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 either a request element, or a resource element (or both). See Transactions for further information. Each entry in a transaction 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' or 'POST', then the entry SHALL contain a resource that becomes the body of the HTTP operation. If there is no request element, then there SHALL be a resource and the server must infer whether this is a create or an update from the resource identity supplied. See Transactions for further information.

Example

2.36.3.4.6 2.37.4.4.6 Transaction/batch Transaction/Batch Response

A transaction response (type = "transaction-response") or batch response (type="batch-response") consists of a series of 0 or more entries, entries: 1 for each entry in the transaction or batch it is in response to. Each entry element SHALL contain 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.37.4.4.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. Bundle. Each entry element SHALL contain a resource.

Example

2.37.4.4.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.37.5 Resource URL & Uniqueness rules in a bundle

Except for transactions and batches, Each each entry in a Bundle must 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, Bundle, a UUID should be used (urn:uuid:...).

For transactions and batches, entries may MAY not have 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 POST so that relationships between resources can be represented (see Transactions ).

In some bundles, a A given version of a resource can SHALL only appear once: Type Rules document no duplicates message no duplicates (generally not, unless noted explicitly once in the event definition e.g. for messaging deltas?) transaction no duplicates allowed transaction-response no duplicates allowed batch no duplicates allowed batch-response no duplicates allowed history yes, duplicates are allowed searchset no duplicates allowed collection yes, duplicates are allowed, though generally each Bundle. There might, however, be multiple versions of a single resource present in a single bundle. This would not 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 good idea resource that appears multiple times is potentially ambiguous, though processors may have additional informaton 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.37.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. Bundle. For example, the system that constructed the bundle Bundle may have included both the observation Observation and the patient. 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 Bundle should always look for a resource by its identity in the bundle first before trying to access it by its URL. URL externally.

How to resolve a reference in a bundle: Bundle:

• If the reference is not an absolute reference, convert it to an absolute URL:
  • If if the reference has the format [type]/[id], and
  • if the fullUrl starts with urn:uuid: or urn:oid:, then append for the id to bundle entry containing the base resource is a RESTful one (see the RESTful URL regex )
    • extract the [root] from the fullUrl, and append the reference (type/id) to it
    • then try to resolve within the bundle as for a RESTful URL reference.
    • If no resolution is possible, then the reference has no defined meaning within this specification
  • if the fullUrl of the resource that contains the reference else no resolution is a RESTful one (see the RESTful URL regex ), extract the [root] , possible and append the reference to it otherwise, treat the fullUrl as a normal URL, and follow the normal method for Resolving Relative References to Absolute Form has no defined meaning within this specification
• else
  • Look for an entry with a fullUrl that contains matches the URL URI in the reference
  • If if no match is found, and the resource URI is not in the bundle, and must a URL that can be found elsewhere resolved (e.g. if an http: URL, URL), try accessing it directly)
  If multiple matches are found, it is ambiguous which is correct

Note, in addition, that a reference may be by identifier, and if it is, and there is no URL, it may be resolved by scanning the ids in the bundle. Note also that transactions may contain conditional references that must be resolved by the server before processing the matches.

If the reference is version specific (either relative or absolute), then remove the version from the URL before matching fullUrl, and then match the version based on Resource.meta.versionId . Note that the rules for resolving references in contained resources are the same as those for resolving resources in the resource that contains the contained resource.

Here If multiple matches are found, it is ambiguous which is correct. Applications MAY return an error or take some other action as they deem appropriate.

There is an example Bundle the that demonstrates these rules: rules.

<Bundle xmlns="http://hl7.org/fhir"> <type value="collection"/> <!-- A patient that already has an id on a server --> <entry> <fullUrl value="http://example.org/fhir/Patient/23"/> <resource> <Patient> <id value="23"/> </Patient> </resource> </entry> <!-- A patient that doesn't have a persistent home - but it does have a UUID assigned for this bundle "locally identified" --> <entry> <fullUrl value="urn:uuid:04121321-4af5-424c-a0e1-ed3aab1c349d"/> <resource> <Patient> </Patient> </resource> </entry> <!-- a relative resource reference --> <entry> <fullUrl value="http://example.org/fhir/Observation/123"/> <resource> <Observation> <id value="123"/> <subject> <!-- this is reference to the first resource above --> <reference value="Patient/23"/> </subject> </Observation> </resource> </entry>

<!-- an absolute reference --> <entry> <fullUrl value="http://example.org/fhir/Observation/124"/> <resource> <Observation> <id value="124"/> <subject> <!-- this is reference to the first resource above --> <reference value="http://example.org/fhir/Patient/23"/> </subject> </Observation> </resource> </entry> 2.37.5.2 Serving Bundles using the RESTful API <!-- reference to a locally identified resource --> <entry> <fullUrl value="http://example.org/fhir/Observation/12"/> <resource> <Observation> <id value="12"/> <subject> <!-- reference to the second patient above --> <reference value="urn:uuid:04121321-4af5-424c-a0e1-ed3aab1c349d"/> </subject> </Observation> </resource> </entry> <!-- reference that doesn't resolve in this bundle --> <entry> <fullUrl value="http://example.org/fhir/Observation/14"/> <resource> <Observation> <id value="14"/> <subject> <!-- reference to a patient not found in this bundle --> <reference value="http://example.org/fhir-2/Patient/1"/> </subject> </Observation> </resource> </entry> </Bundle>

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] 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.

2.36.5 2.37.6 Search Parameters

Search parameters for 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	The first resource in the bundle, if the bundle type is "document" - this is a composition, and this parameter provides access to searches search its contents	Bundle.entry[0].resource ( Composition )
identifier TU	token	Persistent identifier for the bundle	Bundle.identifier
message TU	reference	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 ( MessageHeader
) timestamp TU	date	When the bundle was assembled	Bundle.timestamp
type	token	document | message | transaction | transaction-response | batch | batch-response | history | searchset | collection | subscription-notification	Bundle.type