STU 3 Ballot
FoundationThis page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). 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
| FHIR Infrastructure Work Group | Maturity Level: 2 | Compartments: Not linked to any defined compartments |
A container for a collection of resources.
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:
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:
In addition to these two technical mechanisms, there are three administrative and infrastructure resources which also support grouping of content:
This resource is referenced by measurereport
Structure
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
  Bundle | ΣI | Resource | Contains a collection of resources 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 total only when a search or history entry.search only when a search | |
  type | Σ | 1..1 | code | document | message | transaction | transaction-response | batch | batch-response | history | searchset | collection BundleType (Required) |
| total | ΣI | 0..1 | unsignedInt | If search, the total number of matches |
 link | Σ | 0..* | BackboneElement | 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..* | BackboneElement | Entry in the bundle - will have a resource, or information fullUrl cannot be a version specific reference 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 link | Links related to this entry |
| fullUrl | Σ | 0..1 | uri | Absolute URL for resource (server address, or UUID/OID) |
 resource | Σ | 0..1 | Resource | A resource in the bundle |
| search | ΣI | 0..1 | BackboneElement | Search related information |
| mode | Σ | 0..1 | code | match | include | outcome - why this is in the result set SearchEntryMode (Required) |
| score | Σ | 0..1 | decimal | Search ranking (between 0 and 1) |
| request | ΣI | 0..1 | BackboneElement | Transaction Related Information |
| method | Σ | 1..1 | code | GET | POST | PUT | DELETE HTTPVerb (Required) |
| url | Σ | 1..1 | uri | URL for HTTP equivalent of this entry |
| ifNoneMatch | Σ | 0..1 | string | For managing cache currency |
| ifModifiedSince | Σ | 0..1 | instant | For managing update contention |
| ifMatch | Σ | 0..1 | string | For managing update contention |
| ifNoneExist | Σ | 0..1 | string | For conditional creates |
| response | ΣI | 0..1 | BackboneElement | Transaction Related Information |
 status | Σ | 1..1 | string | Status response code (text optional) |
| 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 |
| outcome | Σ | 0..1 | Resource | OperationOutcome with hints and warnings (for batch/transaction) |
| signature | Σ | 0..1 | Signature | Digital Signature |
| Documentation for this format | ||||
UML Diagram (Legend)
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 | 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> <!--
JSON Template
{
"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 response code (text optional)
"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
"outcome" : { Resource } // OperationOutcome with hints and warnings (for batch/transaction)
}
}],
"signature" : { Signature } // Digital Signature
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> .
Changes since DSTU2
| Bundle | |
| Bundle.entry.response.outcome | added |
See the Full Difference for further information
Structure
| Name | Flags | Card. | Type | Description & Constraints |
|---|---|---|---|---|
| Bundle | ΣI | Resource | Contains a collection of resources 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 total only when a search or history entry.search only when a search | |
| type | Σ | 1..1 | code | document | message | transaction | transaction-response | batch | batch-response | history | searchset | collection BundleType (Required) |
| total | ΣI | 0..1 | unsignedInt | If search, the total number of matches |
| link | Σ | 0..* | BackboneElement | 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..* | BackboneElement | Entry in the bundle - will have a resource, or information fullUrl cannot be a version specific reference 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 link | Links related to this entry |
| fullUrl | Σ | 0..1 | uri | Absolute URL for resource (server address, or UUID/OID) |
| resource | Σ | 0..1 | Resource | A resource in the bundle |
| search | ΣI | 0..1 | BackboneElement | Search related information |
| mode | Σ | 0..1 | code | match | include | outcome - why this is in the result set SearchEntryMode (Required) |
| score | Σ | 0..1 | decimal | Search ranking (between 0 and 1) |
| request | ΣI | 0..1 | BackboneElement | Transaction Related Information |
| method | Σ | 1..1 | code | GET | POST | PUT | DELETE HTTPVerb (Required) |
| url | Σ | 1..1 | uri | URL for HTTP equivalent of this entry |
| ifNoneMatch | Σ | 0..1 | string | For managing cache currency |
| ifModifiedSince | Σ | 0..1 | instant | For managing update contention |
| ifMatch | Σ | 0..1 | string | For managing update contention |
| ifNoneExist | Σ | 0..1 | string | For conditional creates |
| response | ΣI | 0..1 | BackboneElement | Transaction Related Information |
| status | Σ | 1..1 | string | Status response code (text optional) |
| 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 |
| outcome | Σ | 0..1 | Resource | OperationOutcome with hints and warnings (for batch/transaction) |
| signature | Σ | 0..1 | Signature | Digital Signature |
| Documentation for this format | ||||
XML Template
<Bundle xmlns="http://hl7.org/fhir">
JSON Template
{
"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 response code (text optional)
"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
"outcome" : { Resource } // OperationOutcome with hints and warnings (for batch/transaction)
}
}],
"signature" : { Signature } // Digital Signature
}
Turtle Template
@prefix fhir: <http://hl7.org/fhir/> .
Changes since DSTU2
| Bundle | |
| Bundle.entry.response.outcome | added |
See the Full Difference for further information
Alternate definitions: Master Definition (XML, JSON), XML Schema/Schematron (for ) + JSON Schema, ShEx (for Turtle)
| Path | Definition | Type | Reference |
|---|---|---|---|
| Bundle.type | Indicates the purpose of a bundle - how it was 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. | Required | SearchEntryMode |
| Bundle.entry.request.method | HTTP verbs (in the HTTP command line). | Required | HTTPVerb |
: total.empty() or (type = 'searchset') or (type = 'history')): entry.search.empty() or (type = 'searchset')): entry.request.empty() or type = 'batch' or type = 'transaction' or type = 'history'): entry.response.empty() or type = 'batch-response' or type = 'transaction-response') on Bundle.entry: resource.exists() or request.exists() or response.exists()) on Bundle.entry: fullUrl.empty() xor resource.exists()): entry.where(fullUrl).select(fullUrl&resource.meta.versionId).isDistinct()) on Bundle.entry: fullUrl.contains('/_history/').not())link, entry, and search/request/response can all have extensions. See Patient and Location for examples on search).
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 specificThe 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.
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.
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.
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:
An change history (type = "history") consists of a series of 0 or more entries. Each entry element SHALL contain a request element that describes the change that was made, and, if the method is a POST 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 change history, and that may be returned by following the "next" link.
4Example to do
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.
A transaction response (type = "transaction-response") or batch response (type="batch-response")
consists of a series of 0 or more entries, 1 for each entry in the transaction or batch it is in response to.
Each entry element SHALL contain a response element which indicates
the outcome of the HTTP operation that the server performed for the entry.
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.
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 |
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:
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 first resource above -->
<reference value="Patient/23"/>
</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 first resource above -->
<reference value="http://example.org/fhir/Patient/23"/>
</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 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/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>
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 | Paths |
| composition | reference | The first resource in the bundle, if the bundle type is "document" - this is a composition, and this parameter provides access to searches its contents | Bundle.entry(0).resource (Composition) |
| message | 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) |
| type | token | document | message | transaction | transaction-response | batch | batch-response | history | searchset | collection | Bundle.type |
© HL7.org 2011+. FHIR STU3 Ballot (v1.6.0-9663) generated on Thu, Aug 11, 2016 17:06+1000. QA Page
Links: Search |
Version History |
Table of Contents |
Compare to DSTU2 |
|
Propose a change