This page is part of the FHIR Specification (v0.0.82: DSTU 1). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

• Content
• Examples
• Detailed Descriptions
• Mappings
• Profiles

6.8 Resource Bundle - Content

This resource maintained by the FHIR Management Group Work Group

A container for a collection of resources.

6.8.3 Resource Content

• Structure
• UML
• XML
• JSON
• All

Structure

Name	Flags	Card.	Type	Description & Constraints
Bundle	I		Resource	Contains a collection of resources entry.search only when a search total only when a search or history entry.transaction when (and only when) a transaction entry.transactionResponse when (and only when) a transaction-response
type		1..1	code	document | message | transaction | transaction-response | history | searchset | collection BundleType (Required)
base		0..1	uri	Stated Base URL
total	I	0..1	integer	If search, the total number of matches
link		0..*	Element	Links related to this Bundle
relation		1..1	string	http://www.iana.org/assignments/link-relations/link-relations.xhtml
url		1..1	uri	Reference details for the link
entry	I	0..*	Element	Entry in the bundle - will have a resource, or information must be a resource unless there's a transaction or transaction response
base		0..1	uri	Base URL, if different to bundle base
link		0..*	see link	Links related to this entry
resource		0..1	Resource	Resources in this bundle
search	I	0..1	Element	Search related information
mode		0..1	code	match | include - why this is in the result set SearchEntryMode (Required)
score		0..1	decimal	Search ranking (between 0 and 1)
transaction	I	0..1	Element	Transaction Related Information
method		1..1	code	GET | POST | PUT | DELETE HTTPVerb (Required)
url		1..1	uri	The URL for the transaction
ifNoneMatch		0..1	string	For managing cache currency
ifMatch		0..1	string	For managing update contention
ifModifiedSince		0..1	instant	For managing update contention
ifNoneExist		0..1	string	For conditional creates
transactionResponse	I	0..1	Element	Transaction Related Information
status		1..1	string	Status return code for entry
location		0..1	uri	The location, if the operation returns a location
etag		0..1	string	The etag for the resource (if relevant)
lastModified		0..1	instant	Server's date time modified
signature		0..1	base64Binary	XML Digital Signature (base64 encoded)

UML Diagram

XML Template

<Bundle xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <type value="[code]"/><!-- 1..1 document | message | transaction | transaction-response | history | searchset | collection -->
 <base value="[uri]"/><!-- 0..1 Stated Base URL -->
 <total value="[integer]"/><!--  0..1 If search, the total number of matches -->
 <link>  <!-- 0..* Links related to this Bundle -->
  <relation value="[string]"/><!-- 1..1 http://www.iana.org/assignments/link-relations/link-relations.xhtml -->
  <url value="[uri]"/><!-- 1..1 Reference details for the link -->
 </link>
 <entry>  <!-- 0..* Entry in the bundle - will have a resource, or information -->
  <base value="[uri]"/><!-- 0..1 Base URL, if different to bundle base -->
  <link><!-- 0..* Content as for Bundle.link Links related to this entry --></link>
  <resource><!-- 0..1 Resource Resources in this bundle --></resource>
  <search>  <!--  0..1 Search related information -->
   <mode value="[code]"/><!-- 0..1 match | include - why this is in the result set -->
   <score value="[decimal]"/><!-- 0..1 Search ranking (between 0 and 1) -->
  </search>
  <transaction>  <!--  0..1 Transaction Related Information -->
   <method value="[code]"/><!-- 1..1 GET | POST | PUT | DELETE -->
   <url value="[uri]"/><!-- 1..1 The URL for the transaction -->
   <ifNoneMatch value="[string]"/><!-- 0..1 For managing cache currency -->
   <ifMatch value="[string]"/><!-- 0..1 For managing update contention -->
   <ifModifiedSince value="[instant]"/><!-- 0..1 For managing update contention -->
   <ifNoneExist value="[string]"/><!-- 0..1 For conditional creates -->
  </transaction>
  <transactionResponse>  <!--  0..1 Transaction Related Information -->
   <status value="[string]"/><!-- 1..1 Status return code for entry -->
   <location value="[uri]"/><!-- 0..1 The location, if the operation returns a location -->
   <etag value="[string]"/><!-- 0..1 The etag for the resource (if relevant) -->
   <lastModified value="[instant]"/><!-- 0..1 Server's date time modified -->
  </transactionResponse>
 </entry>
 <signature value="[base64Binary]"/><!-- 0..1 XML Digital Signature (base64 encoded) -->
</Bundle>

JSON Template

{
  "resourceType" : "Bundle",
  // from Resource: id, meta, implicitRules, and language
  "type" : "<code>", // R!  document | message | transaction | transaction-response | history | searchset | collection
  "base" : "<uri>", // Stated Base URL
  "total" : <integer>, // C? If search, the total number of matches
  "link" : [{ // Links related to this Bundle
    "relation" : "<string>", // R!  http://www.iana.org/assignments/link-relations/link-relations.xhtml
    "url" : "<uri>" // R!  Reference details for the link
  }],
  "entry" : [{ // Entry in the bundle - will have a resource, or information
    "base" : "<uri>", // Base URL, if different to bundle base
    "link" : [{ Content as for Bundle.link }], // Links related to this entry
    "resource" : { Resource }, // Resources in this bundle
    "search" : { // C? Search related information
      "mode" : "<code>", // match | include - why this is in the result set
      "score" : <decimal> // Search ranking (between 0 and 1)
    },
    "transaction" : { // C? Transaction Related Information
      "method" : "<code>", // R!  GET | POST | PUT | DELETE
      "url" : "<uri>", // R!  The URL for the transaction
      "ifNoneMatch" : "<string>", // For managing cache currency
      "ifMatch" : "<string>", // For managing update contention
      "ifModifiedSince" : "<instant>", // For managing update contention
      "ifNoneExist" : "<string>" // For conditional creates
    },
    "transactionResponse" : { // C? Transaction Related Information
      "status" : "<string>", // R!  Status return code for entry
      "location" : "<uri>", // The location, if the operation returns a location
      "etag" : "<string>", // The etag for the resource (if relevant)
      "lastModified" : "<instant>" // Server's date time modified
    }
  }],
  "signature" : "<base64Binary>" // XML Digital Signature (base64 encoded)
}

Structure

Name	Flags	Card.	Type	Description & Constraints
Bundle	I		Resource	Contains a collection of resources entry.search only when a search total only when a search or history entry.transaction when (and only when) a transaction entry.transactionResponse when (and only when) a transaction-response
type		1..1	code	document | message | transaction | transaction-response | history | searchset | collection BundleType (Required)
base		0..1	uri	Stated Base URL
total	I	0..1	integer	If search, the total number of matches
link		0..*	Element	Links related to this Bundle
relation		1..1	string	http://www.iana.org/assignments/link-relations/link-relations.xhtml
url		1..1	uri	Reference details for the link
entry	I	0..*	Element	Entry in the bundle - will have a resource, or information must be a resource unless there's a transaction or transaction response
base		0..1	uri	Base URL, if different to bundle base
link		0..*	see link	Links related to this entry
resource		0..1	Resource	Resources in this bundle
search	I	0..1	Element	Search related information
mode		0..1	code	match | include - why this is in the result set SearchEntryMode (Required)
score		0..1	decimal	Search ranking (between 0 and 1)
transaction	I	0..1	Element	Transaction Related Information
method		1..1	code	GET | POST | PUT | DELETE HTTPVerb (Required)
url		1..1	uri	The URL for the transaction
ifNoneMatch		0..1	string	For managing cache currency
ifMatch		0..1	string	For managing update contention
ifModifiedSince		0..1	instant	For managing update contention
ifNoneExist		0..1	string	For conditional creates
transactionResponse	I	0..1	Element	Transaction Related Information
status		1..1	string	Status return code for entry
location		0..1	uri	The location, if the operation returns a location
etag		0..1	string	The etag for the resource (if relevant)
lastModified		0..1	instant	Server's date time modified
signature		0..1	base64Binary	XML Digital Signature (base64 encoded)

UML Diagram

XML Template

<Bundle xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <type value="[code]"/><!-- 1..1 document | message | transaction | transaction-response | history | searchset | collection -->
 <base value="[uri]"/><!-- 0..1 Stated Base URL -->
 <total value="[integer]"/><!--  0..1 If search, the total number of matches -->
 <link>  <!-- 0..* Links related to this Bundle -->
  <relation value="[string]"/><!-- 1..1 http://www.iana.org/assignments/link-relations/link-relations.xhtml -->
  <url value="[uri]"/><!-- 1..1 Reference details for the link -->
 </link>
 <entry>  <!-- 0..* Entry in the bundle - will have a resource, or information -->
  <base value="[uri]"/><!-- 0..1 Base URL, if different to bundle base -->
  <link><!-- 0..* Content as for Bundle.link Links related to this entry --></link>
  <resource><!-- 0..1 Resource Resources in this bundle --></resource>
  <search>  <!--  0..1 Search related information -->
   <mode value="[code]"/><!-- 0..1 match | include - why this is in the result set -->
   <score value="[decimal]"/><!-- 0..1 Search ranking (between 0 and 1) -->
  </search>
  <transaction>  <!--  0..1 Transaction Related Information -->
   <method value="[code]"/><!-- 1..1 GET | POST | PUT | DELETE -->
   <url value="[uri]"/><!-- 1..1 The URL for the transaction -->
   <ifNoneMatch value="[string]"/><!-- 0..1 For managing cache currency -->
   <ifMatch value="[string]"/><!-- 0..1 For managing update contention -->
   <ifModifiedSince value="[instant]"/><!-- 0..1 For managing update contention -->
   <ifNoneExist value="[string]"/><!-- 0..1 For conditional creates -->
  </transaction>
  <transactionResponse>  <!--  0..1 Transaction Related Information -->
   <status value="[string]"/><!-- 1..1 Status return code for entry -->
   <location value="[uri]"/><!-- 0..1 The location, if the operation returns a location -->
   <etag value="[string]"/><!-- 0..1 The etag for the resource (if relevant) -->
   <lastModified value="[instant]"/><!-- 0..1 Server's date time modified -->
  </transactionResponse>
 </entry>
 <signature value="[base64Binary]"/><!-- 0..1 XML Digital Signature (base64 encoded) -->
</Bundle>

JSON Template

{
  "resourceType" : "Bundle",
  // from Resource: id, meta, implicitRules, and language
  "type" : "<code>", // R!  document | message | transaction | transaction-response | history | searchset | collection
  "base" : "<uri>", // Stated Base URL
  "total" : <integer>, // C? If search, the total number of matches
  "link" : [{ // Links related to this Bundle
    "relation" : "<string>", // R!  http://www.iana.org/assignments/link-relations/link-relations.xhtml
    "url" : "<uri>" // R!  Reference details for the link
  }],
  "entry" : [{ // Entry in the bundle - will have a resource, or information
    "base" : "<uri>", // Base URL, if different to bundle base
    "link" : [{ Content as for Bundle.link }], // Links related to this entry
    "resource" : { Resource }, // Resources in this bundle
    "search" : { // C? Search related information
      "mode" : "<code>", // match | include - why this is in the result set
      "score" : <decimal> // Search ranking (between 0 and 1)
    },
    "transaction" : { // C? Transaction Related Information
      "method" : "<code>", // R!  GET | POST | PUT | DELETE
      "url" : "<uri>", // R!  The URL for the transaction
      "ifNoneMatch" : "<string>", // For managing cache currency
      "ifMatch" : "<string>", // For managing update contention
      "ifModifiedSince" : "<instant>", // For managing update contention
      "ifNoneExist" : "<string>" // For conditional creates
    },
    "transactionResponse" : { // C? Transaction Related Information
      "status" : "<string>", // R!  Status return code for entry
      "location" : "<uri>", // The location, if the operation returns a location
      "etag" : "<string>", // The etag for the resource (if relevant)
      "lastModified" : "<instant>" // Server's date time modified
    }
  }],
  "signature" : "<base64Binary>" // XML Digital Signature (base64 encoded)
}

Alternate definitions: Schema/Schematron, Resource Profile (XML, JSON), Questionnaire

6.8.3.1 Terminology Bindings

6.8.3.2 Constraints

• bdl-1: total only when a search or history (xpath: not(f:total) or (f:type/@value = 'searchset') or (f:type/@value = 'history'))
• bdl-2: entry.search only when a search (xpath: not(f:entry/f:search) or (f:type/@value = 'searchset'))
• bdl-3: entry.transaction when (and only when) a transaction (xpath: not(f:entry/f:transaction) or (f:type/@value = 'transaction') or (f:type/@value = 'history'))
• bdl-4: entry.transactionResponse when (and only when) a transaction-response (xpath: not(f:entry/f:transactionResponse) or (f:type/@value = 'transaction-response'))
• bdl-5: On Bundle.entry: must be a resource unless there's a transaction or transaction response (xpath on f:Bundle/f:entry: f:resource or f:transaction or f:transactionResponse)

6.8.3.3 Notes

• 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
• 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

6.8.3.4 Using Bundles

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

6.8.3.4.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 a resource. See Documents for further information.

Example

6.8.3.4.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 a resource. See Messaging for further information.

Example: todo

6.8.3.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, 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

6.8.3.4.4 History

An update history (type = "history") consists of a series of 0 or more entries. Each entry element SHALL contain a transaction element that describes the change that was 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. See History for further information.

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

Example to do

6.8.3.4.5 Transaction

A transaction (type = "transaction") consists of a series of 0 or more entries. Each entry element MAY contain a transaction element, and MAY contain either a resource element. 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 transaction element, then there SHALL be a resource and the server must infer whether this is a create or an update from from the resource identity supplied.

Example

6.8.3.4.6 Transaction Response

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

Example

6.8.3.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. Each entry element SHALL contain a resource.

Example

6.8.3.5 Resolving references in Bundles

Bundle has a 'base' element, which is used to resolve relative references present in the bundled resources. In the case that the bundle includes resources with different bases, each entry can also assert its applicable base if this is different to the overall base. A base SHOULD always be specified, either in the bundle itself, or on each entry.

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.

The id property of a resource is a relative URI. In the case of the RESTful API, the id is relative to the system base URL such that the absolute URI of the resource is:

[base]/[Type]/[id]

When resolving references with in a bundle, the resolution is against the absolute URI. For instance, if a resource with a stated base of http://example.org/fhir has a reference with a value of Patient/2341, then it will resolve to a Patient resource with an id of 2341 and a base of http://example.org/fhir, which is an absolute URI of http://example.org/fhir/Patient/2341.

There is one special case: for a base URI of urn:uuid: or urn:oid:, the absolute URI does not include the type of the resource:

[base][id]

OIDs and UUIDs are intended for use where the resource the entry is for has no established identity on an existing RESTful interface.

6.8.4 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.