Connectathon 11 Snapshot

This page is part of the FHIR Specification (v1.2.0: STU 3 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.7 Resource Bundle - Content

FHIR Infrastructure Work GroupMaturity Level: 2Compartments: Not linked to any defined compartments

A container for a collection of resources.

6.7.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 collection with clinical integrity - e.g. a clinical document (see Documents)
  • Creating/updating/deleting a set of resources on a server as a single operation (including doing so as a single atomic transaction) (see Transactions)
  • Storing a collection of resources

6.7.2 Boundaries and Relationships

There are two ways to collect resources together for transport and persistence purposes - 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 collection of resources that have an independent existence - for example, they can also be accessed directly using the RESTful API

In addition to these two technical mechanisms, there are three administrative and infrastructure resources which also support grouping of content:

  • The List resource – Enumerates a flat collection of resources and provides features for managing the collection. While a particular List instance may represent a "snapshot", from a business process perspective the notion of "List" is dynamic – items are added and removed over time. The list resource references other resources. Lists may be curated and have specific business meaning.
  • The Group resource – Defines a group of specific people, animals, devices, etc. by enumerating them, or by describing qualities that group members have. The group resource refers to other resources, possibly implicitly. Groups are intended to be acted upon or observed as a whole; e.g. performing therapy on a group, calculating risk for a group, etc. This resource will commonly be used for public health (e.g. describing an at-risk population), clinical trials (e.g. defining a test subject pool) and similar purposes.
  • The Composition resource – Defines a set of healthcare-related information that is assembled together into a single logical document that provides a single coherent statement of meaning, establishes its own context and that has clinical attestation with regard to who is making the statement. The composition resource provides the basic structure of a FHIR document. The full content of the document is expressed using a bundle. Compositions will often reference Lists as the focus of particular sections.

6.7.3 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Bundle Σ IResourceContains a collection of resources
entry.search only when a search
total only when a search or history
FullUrl must be unique in a bundle, or else entries with the same fullUrl must have different meta.versionId
entry.request only for some types of bundles
entry.response only for some types of bundles
... type Σ1..1codedocument | message | transaction | transaction-response | batch | batch-response | history | searchset | collection
BundleType (Required)
... total Σ I0..1unsignedIntIf search, the total number of matches
... link Σ0..*BackboneElementLinks 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..*BackboneElementEntry in the bundle - will have a resource, or information
must be a resource unless there's a request or response
The fullUrl element must be present when a resource is present, and not present otherwise
.... link Σ0..*see linkLinks related to this entry
.... fullUrl Σ0..1uriAbsolute URL for resource (server address, or UUID/OID)
.... resource Σ0..1ResourceA resource in the bundle
.... search Σ I0..1BackboneElementSearch related information
..... mode Σ0..1codematch | include | outcome - why this is in the result set
SearchEntryMode (Required)
..... score Σ0..1decimalSearch ranking (between 0 and 1)
.... request Σ I0..1BackboneElementTransaction Related Information
..... method Σ1..1codeGET | POST | PUT | DELETE
HTTPVerb (Required)
..... url Σ1..1uriURL for HTTP equivalent of this entry
..... ifNoneMatch Σ0..1stringFor managing cache currency
..... ifModifiedSince Σ0..1instantFor managing update contention
..... ifMatch Σ0..1stringFor managing update contention
..... ifNoneExist Σ0..1stringFor conditional creates
.... response Σ I0..1BackboneElementTransaction 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..1SignatureDigital Signature

doco Documentation for this format

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 used. (Strength=Required)BundleType! »If 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 : unsignedInt [0..1]Digital Signature - base64 encoded. XML DigSIg or a JWTsignature : Signature [0..1]LinkA name which details the functional use for this link - see [[http://www.iana.org/assignments/link-relations/link-relations.xhtml]]relation : string [1..1]The reference details for the linkurl : uri [1..1]EntryThe Absolute URL for the resource. This must be provided for all resources. The fullUrl SHALL not disagree with the id in the resource. The fullUrl is a version independent reference to the resourcefullUrl : uri [0..1]The Resources for the entryresource : Resource [0..1]SearchWhy 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 requirement. (Strength=Required)SearchEntryMode! »When searching, the server's search ranking score for the entryscore : decimal [0..1]RequestThe 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). (Strength=Required)HTTPVerb! »The URL for this entry, relative to the root (the address to which the request is posted)url : uri [1..1]If the ETag values match, return a 304 Not modified status. See the API documentation for ["Conditional Read"](http.html#cread)ifNoneMatch : string [0..1]Only perform the operation if the last updated date matches. See the API documentation for ["Conditional Read"](http.html#cread)ifModifiedSince : instant [0..1]Only perform the operation if the Etag value matches. For more information, see the API section ["Managing Resource Contention"](http.html#concurrency)ifMatch : string [0..1]Instruct the server not to perform the create if a specified resource already exists. For further information, see the API documentation for ["Conditional Create"](http.html#ccreate). This is just the query portion of the URL - what follows the "?" (not including the "?")ifNoneExist : string [0..1]ResponseThe status code returned by processing this entrystatus : string [1..1]The location header created by processing this operationlocation : uri [0..1]The etag for the resource, it the operation for the entry produced a versioned resourceetag : string [0..1]The date/time that the resource was modified on the serverlastModified : instant [0..1]A series of links that provide context to this bundlelink[0..*]A series of links that provide context to this entrylink[0..*]Information about the search process that lead to the creation of this entrysearch[0..1]Additional information about how this entry should be processed as part of a transactionrequest[0..1]Additional information about how this entry should be processed as part of a transactionresponse[0..1]An entry in a bundle resource - will either contain a resource, or information about a resource (transactions and history only)entry[0..*]

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 | batch | batch-response | history | searchset | collection -->
 <total value="[unsignedInt]"/><!-- ?? 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 -->
  <link><!-- 0..* Content as for Bundle.link Links related to this entry --></link>
  <fullUrl value="[uri]"/><!-- 0..1 Absolute URL for resource (server address, or UUID/OID) -->
  <resource><!-- 0..1 Resource A resource in the bundle --></resource>
  <search>  <!-- ?? 0..1 Search related information -->
   <mode value="[code]"/><!-- 0..1 match | include | outcome - why this is in the result set -->
   <score value="[decimal]"/><!-- 0..1 Search ranking (between 0 and 1) -->
  </search>
  <request>  <!-- ?? 0..1 Transaction Related Information -->
   <method value="[code]"/><!-- 1..1 GET | POST | PUT | DELETE -->
   <url value="[uri]"/><!-- 1..1 URL for HTTP equivalent of this entry -->
   <ifNoneMatch value="[string]"/><!-- 0..1 For managing cache currency -->
   <ifModifiedSince value="[instant]"/><!-- 0..1 For managing update contention -->
   <ifMatch value="[string]"/><!-- 0..1 For managing update contention -->
   <ifNoneExist value="[string]"/><!-- 0..1 For conditional creates -->
  </request>
  <response>  <!-- ?? 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 -->
  </response>
 </entry>
 <signature><!-- 0..1 Signature Digital Signature --></signature>
</Bundle>

JSON Template

{doco
  "resourceType" : "Bundle",
  // from Resource: id, meta, implicitRules, and language
  "type" : "<code>", // R!  document | message | transaction | transaction-response | batch | batch-response | history | searchset | collection
  "total" : "<unsignedInt>", // 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
    "link" : [{ Content as for Bundle.link }], // Links related to this entry
    "fullUrl" : "<uri>", // Absolute URL for resource (server address, or UUID/OID)
    "resource" : { Resource }, // A resource in the bundle
    "search" : { // C? Search related information
      "mode" : "<code>", // match | include | outcome - why this is in the result set
      "score" : <decimal> // Search ranking (between 0 and 1)
    },
    "request" : { // C? Transaction Related Information
      "method" : "<code>", // R!  GET | POST | PUT | DELETE
      "url" : "<uri>", // R!  URL for HTTP equivalent of this entry
      "ifNoneMatch" : "<string>", // For managing cache currency
      "ifModifiedSince" : "<instant>", // For managing update contention
      "ifMatch" : "<string>", // For managing update contention
      "ifNoneExist" : "<string>" // For conditional creates
    },
    "response" : { // 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" : { Signature } // Digital Signature
}

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. Bundle Σ IResourceContains a collection of resources
entry.search only when a search
total only when a search or history
FullUrl must be unique in a bundle, or else entries with the same fullUrl must have different meta.versionId
entry.request only for some types of bundles
entry.response only for some types of bundles
... type Σ1..1codedocument | message | transaction | transaction-response | batch | batch-response | history | searchset | collection
BundleType (Required)
... total Σ I0..1unsignedIntIf search, the total number of matches
... link Σ0..*BackboneElementLinks 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..*BackboneElementEntry in the bundle - will have a resource, or information
must be a resource unless there's a request or response
The fullUrl element must be present when a resource is present, and not present otherwise
.... link Σ0..*see linkLinks related to this entry
.... fullUrl Σ0..1uriAbsolute URL for resource (server address, or UUID/OID)
.... resource Σ0..1ResourceA resource in the bundle
.... search Σ I0..1BackboneElementSearch related information
..... mode Σ0..1codematch | include | outcome - why this is in the result set
SearchEntryMode (Required)
..... score Σ0..1decimalSearch ranking (between 0 and 1)
.... request Σ I0..1BackboneElementTransaction Related Information
..... method Σ1..1codeGET | POST | PUT | DELETE
HTTPVerb (Required)
..... url Σ1..1uriURL for HTTP equivalent of this entry
..... ifNoneMatch Σ0..1stringFor managing cache currency
..... ifModifiedSince Σ0..1instantFor managing update contention
..... ifMatch Σ0..1stringFor managing update contention
..... ifNoneExist Σ0..1stringFor conditional creates
.... response Σ I0..1BackboneElementTransaction 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..1SignatureDigital Signature

doco Documentation for this format

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 used. (Strength=Required)BundleType! »If 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 : unsignedInt [0..1]Digital Signature - base64 encoded. XML DigSIg or a JWTsignature : Signature [0..1]LinkA name which details the functional use for this link - see [[http://www.iana.org/assignments/link-relations/link-relations.xhtml]]relation : string [1..1]The reference details for the linkurl : uri [1..1]EntryThe Absolute URL for the resource. This must be provided for all resources. The fullUrl SHALL not disagree with the id in the resource. The fullUrl is a version independent reference to the resourcefullUrl : uri [0..1]The Resources for the entryresource : Resource [0..1]SearchWhy 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 requirement. (Strength=Required)SearchEntryMode! »When searching, the server's search ranking score for the entryscore : decimal [0..1]RequestThe 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). (Strength=Required)HTTPVerb! »The URL for this entry, relative to the root (the address to which the request is posted)url : uri [1..1]If the ETag values match, return a 304 Not modified status. See the API documentation for ["Conditional Read"](http.html#cread)ifNoneMatch : string [0..1]Only perform the operation if the last updated date matches. See the API documentation for ["Conditional Read"](http.html#cread)ifModifiedSince : instant [0..1]Only perform the operation if the Etag value matches. For more information, see the API section ["Managing Resource Contention"](http.html#concurrency)ifMatch : string [0..1]Instruct the server not to perform the create if a specified resource already exists. For further information, see the API documentation for ["Conditional Create"](http.html#ccreate). This is just the query portion of the URL - what follows the "?" (not including the "?")ifNoneExist : string [0..1]ResponseThe status code returned by processing this entrystatus : string [1..1]The location header created by processing this operationlocation : uri [0..1]The etag for the resource, it the operation for the entry produced a versioned resourceetag : string [0..1]The date/time that the resource was modified on the serverlastModified : instant [0..1]A series of links that provide context to this bundlelink[0..*]A series of links that provide context to this entrylink[0..*]Information about the search process that lead to the creation of this entrysearch[0..1]Additional information about how this entry should be processed as part of a transactionrequest[0..1]Additional information about how this entry should be processed as part of a transactionresponse[0..1]An entry in a bundle resource - will either contain a resource, or information about a resource (transactions and history only)entry[0..*]

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 | batch | batch-response | history | searchset | collection -->
 <total value="[unsignedInt]"/><!-- ?? 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 -->
  <link><!-- 0..* Content as for Bundle.link Links related to this entry --></link>
  <fullUrl value="[uri]"/><!-- 0..1 Absolute URL for resource (server address, or UUID/OID) -->
  <resource><!-- 0..1 Resource A resource in the bundle --></resource>
  <search>  <!-- ?? 0..1 Search related information -->
   <mode value="[code]"/><!-- 0..1 match | include | outcome - why this is in the result set -->
   <score value="[decimal]"/><!-- 0..1 Search ranking (between 0 and 1) -->
  </search>
  <request>  <!-- ?? 0..1 Transaction Related Information -->
   <method value="[code]"/><!-- 1..1 GET | POST | PUT | DELETE -->
   <url value="[uri]"/><!-- 1..1 URL for HTTP equivalent of this entry -->
   <ifNoneMatch value="[string]"/><!-- 0..1 For managing cache currency -->
   <ifModifiedSince value="[instant]"/><!-- 0..1 For managing update contention -->
   <ifMatch value="[string]"/><!-- 0..1 For managing update contention -->
   <ifNoneExist value="[string]"/><!-- 0..1 For conditional creates -->
  </request>
  <response>  <!-- ?? 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 -->
  </response>
 </entry>
 <signature><!-- 0..1 Signature Digital Signature --></signature>
</Bundle>

JSON Template

{doco
  "resourceType" : "Bundle",
  // from Resource: id, meta, implicitRules, and language
  "type" : "<code>", // R!  document | message | transaction | transaction-response | batch | batch-response | history | searchset | collection
  "total" : "<unsignedInt>", // 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
    "link" : [{ Content as for Bundle.link }], // Links related to this entry
    "fullUrl" : "<uri>", // Absolute URL for resource (server address, or UUID/OID)
    "resource" : { Resource }, // A resource in the bundle
    "search" : { // C? Search related information
      "mode" : "<code>", // match | include | outcome - why this is in the result set
      "score" : <decimal> // Search ranking (between 0 and 1)
    },
    "request" : { // C? Transaction Related Information
      "method" : "<code>", // R!  GET | POST | PUT | DELETE
      "url" : "<uri>", // R!  URL for HTTP equivalent of this entry
      "ifNoneMatch" : "<string>", // For managing cache currency
      "ifModifiedSince" : "<instant>", // For managing update contention
      "ifMatch" : "<string>", // For managing update contention
      "ifNoneExist" : "<string>" // For conditional creates
    },
    "response" : { // 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" : { Signature } // Digital Signature
}

 

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

6.7.3.1 Terminology Bindings

PathDefinitionTypeReference
Bundle.type Indicates the purpose of a bundle - how it was intended to be used.RequiredBundleType
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.RequiredSearchEntryMode
Bundle.entry.request.method HTTP verbs (in the HTTP command line).RequiredHTTPVerb

6.7.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.request only for some types of bundles (xpath: not(f:entry/f:request) or (f:type/@value = 'batch') or (f:type/@value = 'transaction') or (f:type/@value = 'history'))
  • bdl-4: entry.response only for some types of bundles (xpath: not(f:entry/f:response) or (f:type/@value = 'batch-response') or (f:type/@value = 'transaction-response'))
  • bdl-5: On Bundle.entry: must be a resource unless there's a request or response (xpath on f:Bundle/f:entry: f:resource or f:request or f:response)
  • bdl-6: On Bundle.entry: The fullUrl element must be present when a resource is present, and not present otherwise (xpath on f:Bundle/f:entry: (not(exists(f:fullUrl)) and not(exists(f:resource))) or (exists(f:fullUrl) and exists(f:resource)))
  • bdl-7: FullUrl must be unique in a bundle, or else entries with the same fullUrl must have different meta.versionId (xpath: count(for $entry in f:entry[f:resource] return $entry[count(parent::f:Bundle/f:entry[f:fullUrl/@value=$entry/f:fullUrl/@value and ((not(f:resource/*/f:meta/f:versionId/@value) and not($entry/f:resource/*/f:meta/f:versionId/@value)) or f:resource/*/f:meta/f:versionId/@value=$entry/f:resource/*/f:meta/f:versionId/@value)])!=1])=0)

6.7.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.7.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 resource identity resolution as described below.

6.7.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.7.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 Request and Response

6.7.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.7.3.4.4 History

An update 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 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.

4

Example to do

6.7.3.4.5 Transaction

A transaction (type = "transaction") 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.

Example

6.7.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 response element which indicates the outcome of the HTTP operation that the server performed for the entry.

Example

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

Each entry in a batch must have a full Url 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 be used (urn:uuid:...).

In some bundles, a given resource can only appear once:

Type Rules
document no duplicates (weird edge cases - change tracking?)
message no duplicates (well, 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 would not be a good idea

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

How to resolve a reference in a bundle:

  1. If the reference is not an absolute reference, convert it
    • if the fullUrl is a uri, then (you're stuffed!) What to do in this case?
    • if the fullUrl of the resource that contains the reference is a RESTful one (see the RESTful URL regex), extract the [base], 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
  2. Look for an entry with a fullUrl that contains the URL in the reference
    • If no match is found, the resource is not in the bundle, and must be found elsewhere (e.g. if an http: URL, try accessing it directly)
    • If multiple matches are found, it is ambiguous which is correct

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.

Here is an example Bundle the demonstrates these 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 resource above -->
           <reference value="Patient/1"/>
         </subject>
      </Organization>
    </resource>
  <entry>

  <!-- an absolute reference -->
  <entry>
    <fullUrl value="http://example.org/fhir/Observation/123"/>
    <resource>
      <Observation>
         <id value="123"/>
         <subject>
           <!-- this is reference to the resource above -->
           <reference value="http://example.org/fhir/Patient/1"/>
         </subject>
      </Organization>
    </resource>
  <entry>

  <!-- reference to a locally identified resource -->
  <entry>
    <fullUrl value="http://example.org/fhir/Observation/12"/>
    <resource>
      <Observation>
         <id value="12"/>
         <subject>
           <!-- reference to the patient immediately 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/12"/>
    <resource>
      <Observation>
         <id value="12"/>
         <subject>
           <!-- reference to a patient not found in this bundle -->
           <reference value="http://example.org/fhir-2/Patient/1"/>
         </subject>
      </Observation>
    </resource>
  <entry>
  
</Bundle>

6.7.5 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 its contentsBundle.entry.resource(0)
(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 its contentsBundle.entry.resource(0)
(MessageHeader)
typetokendocument | message | transaction | transaction-response | batch | batch-response | history | searchset | collectionBundle.type