2nd DSTU Draft For Comment

This page is part of the FHIR Specification (v0.4.0: DSTU 2 Draft). 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

6.8 Resource Bundle - Content

This resource maintained by the FHIR Management Group Work Group

A container for a group of resources.

6.8.1 Scope and Usage

One common operation performed with resources is to gather a collection of resources into a single instance with containing context. In FHIR this is referred to as "bundling" the resources together. These resource bundles are useful for a variety of different reasons, including:

  • Returning a set of resources that meet some criteria as part of a server operation (see RESTful Search)
  • Returning a set of versions of resources as part of the history operation on a server (see History)
  • Sending a set of resources as part of a message exchange (see Messaging)
  • Grouping a self-contained set of resources to act as an exchangeable and persistable group with clinical integrity - e.g. a clinical document (see Documents)
  • Creating/updating/deleting a set of resources as a single atomic transaction on a server (see Transactions)
  • Storing a collection of resources

6.8.2 Boundaries and Relationships

There are two ways to group resources together - contained resources, and bundles. There is an important difference between the two:

  • Contained resources are "in" the container resource - they can only ever be interpreted and/or changed in the context of the container
  • A bundle is a group of resources that have an independent existence - the source of the resource can be determined by the base (see below) and the logical id

6.8.3 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Bundle IResourceContains a group 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..1codedocument | message | transaction | transaction-response | history | searchset | collection
BundleType (Required)
... base 0..1uriStated Base URL
... total I0..1integerIf search, the total number of matches
... link 0..*ElementLinks related to this Bundle
.... relation 1..1stringhttp://www.iana.org/assignments/link-relations/link-relations.xhtml
.... url 1..1uriReference details for the link
... entry I0..*ElementEntry in the bundle - will have a resource, or information
must be a resource unless there's a transaction or transaction response
.... base 0..1uriBase URL, if different to bundle base
.... resource 0..1ResourceResources in this bundle
.... search I0..1ElementSearch related information
..... mode 0..1codematch | include - why this is in the result set
SearchEntryMode (Required)
..... score 0..1decimalSearch ranking (between 0 and 1)
.... transaction I0..1ElementTransaction Related Information
..... method 1..1codeGET | POST | PUT | DELETE
HTTPVerb (Required)
..... url 1..1uriThe URL for the transaction
..... ifNoneMatch 0..1stringFor managing cache currency
..... ifMatch 0..1stringFor managing update contention
..... ifModifiedSince 0..1instantFor managing update contention
..... ifNoneExist 0..1stringFor conditional creates
.... transactionResponse I0..1ElementTransaction Related Information
..... status 1..1stringStatus return code for entry
..... location 0..1uriThe location, if the operation returns a location
..... etag 0..1stringThe etag for the resource (if relevant)
..... lastModified 0..1instantServer's date time modified
... signature 0..1base64BinaryXML Digital Signature (base64 encoded)

UML Diagram

Bundle (Resource)Indicates the purpose of this bundle- how it was intended to be usedtype : code 1..1 « Indicates the purpose of a bundle- how it was intended to be usedBundleType »The base URL for the service that provided these resources. All relative URLs are relative to this one (equivalent to xml:base)base : uri 0..1If a set of search matches, this is the total number of matches for the search (as opposed to the number of results in this bundle)total : integer 0..1XML Digital Signature - base64 encodedsignature : base64Binary 0..1LinkA name which details the functional use for this link - see [[http://www.iana.org/assignments/link-relations/link-relations.xhtml]]relation : string 1..1The reference details for the linkurl : uri 1..1EntryThe Base URL for the resource, if different to the base URL specified for the bundle as a wholebase : uri 0..1The Resources for the entryresource : Resource 0..1SearchWhy this entry is in the result set - whether it's included as a match or because of an _include requirementmode : code 0..1 « Why an entry is in the result set - whether it's included as a match or because of an _include requirementSearchEntryMode »When searching, the server's search ranking score for the entryscore : decimal 0..1TransactionThe HTTP verb for this entry in either a update history, or a transaction/ transaction responsemethod : code 1..1 « HTTP verbs (in the HTTP command line)HTTPVerb »A search URL for this resource that specifies how the resource is matched to an existing resource when processing a transaction (see transaction documentation)url : uri 1..1If the ETag values match, return a 304 Not modified status. See the read/vread interaction documentationifNoneMatch : string 0..1Only perform the operation if the Etag value matches. For more information, see the API section "Managing Resource Contention"ifMatch : string 0..1Only perform the operation if the last updated date matches. For more information, see the API section "Managing Resource Contention"ifModifiedSince : instant 0..1Instruct the server not to perform the create if a specified resource already exists. For further information, see "Conditional Create"ifNoneExist : string 0..1TransactionResponseThe status code returned by processing this entrystatus : string 1..1The location header created by processing this operationlocation : uri 0..1The etag for the resource, it the operation for the entry produced a versioned resourceetag : string 0..1The date/time that the resource was modified on the serverlastModified : instant 0..1A series of links that provide context to this bundlelink0..*Information about the search process that lead to the creation of this entrysearch0..1Additional information about how this entry should be processed as part of a transactiontransaction0..1Additional information about how this entry should be processed as part of a transactiontransactionResponse0..1An entry in a bundle resource - will either contain a resource, or information about a resource (transactions and history only)entry0..*

XML Template

<Bundle xmlns="http://hl7.org/fhir"> doco
 <!-- 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 -->
  <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

{doco
  "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
    "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

NameFlagsCard.TypeDescription & Constraintsdoco
.. Bundle IResourceContains a group 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..1codedocument | message | transaction | transaction-response | history | searchset | collection
BundleType (Required)
... base 0..1uriStated Base URL
... total I0..1integerIf search, the total number of matches
... link 0..*ElementLinks related to this Bundle
.... relation 1..1stringhttp://www.iana.org/assignments/link-relations/link-relations.xhtml
.... url 1..1uriReference details for the link
... entry I0..*ElementEntry in the bundle - will have a resource, or information
must be a resource unless there's a transaction or transaction response
.... base 0..1uriBase URL, if different to bundle base
.... resource 0..1ResourceResources in this bundle
.... search I0..1ElementSearch related information
..... mode 0..1codematch | include - why this is in the result set
SearchEntryMode (Required)
..... score 0..1decimalSearch ranking (between 0 and 1)
.... transaction I0..1ElementTransaction Related Information
..... method 1..1codeGET | POST | PUT | DELETE
HTTPVerb (Required)
..... url 1..1uriThe URL for the transaction
..... ifNoneMatch 0..1stringFor managing cache currency
..... ifMatch 0..1stringFor managing update contention
..... ifModifiedSince 0..1instantFor managing update contention
..... ifNoneExist 0..1stringFor conditional creates
.... transactionResponse I0..1ElementTransaction Related Information
..... status 1..1stringStatus return code for entry
..... location 0..1uriThe location, if the operation returns a location
..... etag 0..1stringThe etag for the resource (if relevant)
..... lastModified 0..1instantServer's date time modified
... signature 0..1base64BinaryXML Digital Signature (base64 encoded)

UML Diagram

Bundle (Resource)Indicates the purpose of this bundle- how it was intended to be usedtype : code 1..1 « Indicates the purpose of a bundle- how it was intended to be usedBundleType »The base URL for the service that provided these resources. All relative URLs are relative to this one (equivalent to xml:base)base : uri 0..1If a set of search matches, this is the total number of matches for the search (as opposed to the number of results in this bundle)total : integer 0..1XML Digital Signature - base64 encodedsignature : base64Binary 0..1LinkA name which details the functional use for this link - see [[http://www.iana.org/assignments/link-relations/link-relations.xhtml]]relation : string 1..1The reference details for the linkurl : uri 1..1EntryThe Base URL for the resource, if different to the base URL specified for the bundle as a wholebase : uri 0..1The Resources for the entryresource : Resource 0..1SearchWhy this entry is in the result set - whether it's included as a match or because of an _include requirementmode : code 0..1 « Why an entry is in the result set - whether it's included as a match or because of an _include requirementSearchEntryMode »When searching, the server's search ranking score for the entryscore : decimal 0..1TransactionThe HTTP verb for this entry in either a update history, or a transaction/ transaction responsemethod : code 1..1 « HTTP verbs (in the HTTP command line)HTTPVerb »A search URL for this resource that specifies how the resource is matched to an existing resource when processing a transaction (see transaction documentation)url : uri 1..1If the ETag values match, return a 304 Not modified status. See the read/vread interaction documentationifNoneMatch : string 0..1Only perform the operation if the Etag value matches. For more information, see the API section "Managing Resource Contention"ifMatch : string 0..1Only perform the operation if the last updated date matches. For more information, see the API section "Managing Resource Contention"ifModifiedSince : instant 0..1Instruct the server not to perform the create if a specified resource already exists. For further information, see "Conditional Create"ifNoneExist : string 0..1TransactionResponseThe status code returned by processing this entrystatus : string 1..1The location header created by processing this operationlocation : uri 0..1The etag for the resource, it the operation for the entry produced a versioned resourceetag : string 0..1The date/time that the resource was modified on the serverlastModified : instant 0..1A series of links that provide context to this bundlelink0..*Information about the search process that lead to the creation of this entrysearch0..1Additional information about how this entry should be processed as part of a transactiontransaction0..1Additional information about how this entry should be processed as part of a transactiontransactionResponse0..1An entry in a bundle resource - will either contain a resource, or information about a resource (transactions and history only)entry0..*

XML Template

<Bundle xmlns="http://hl7.org/fhir"> doco
 <!-- 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 -->
  <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

{doco
  "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
    "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

PathDefinitionTypeReference
Bundle.type Indicates the purpose of a bundle- how it was intended to be usedFixedhttp://hl7.org/fhir/bundle-type
Bundle.entry.search.mode Why an entry is in the result set - whether it's included as a match or because of an _include requirementFixedhttp://hl7.org/fhir/search-entry-mode
Bundle.entry.transaction.method HTTP verbs (in the HTTP command line)Fixedhttp://hl7.org/fhir/http-verb

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

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

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 it's 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.

NameTypeDescriptionPaths
compositionreferenceThe first resource in the bundle, if the bundle type is "document" - this is a composition, and this parameter provides access to searches it's contents
(Composition)
messagereferenceThe first resource in the bundle, if the bundle type is "message" - this is a message header, and this parameter provides access to search it's contents
(MessageHeader)
typetokendocument | message | transaction | transaction-response | history | searchset | collectionBundle.type