6.7.1
Scope
and
Usage
2.35.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
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
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
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
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
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
Storing a collection of resources
6.7.2
Boundaries
and
Relationships
2.35.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
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
In addition to these two technical mechanisms, there are three administrative and infrastructure resources which also support grouping of content:
Contains
a
collection
of
resources
Contains a collection of resources
entry.search
only
when
a
search
FullUrl must be unique in a bundle, or else entries with the same fullUrl must have different meta.versionId
total
only
when
a
search
or
history
entry.request only for some types of bundles
FullUrl
must
be
unique
in
a
bundle,
or
else
entries
with
the
same
fullUrl
must
have
different
meta.versionId
entry.response only for some types of bundles
entry.request
only
for
some
types
of
bundles
total only when a search or history
entry.response
only
for
some
types
of
bundles
entry.search only when a search
Entry
in
the
bundle
-
will
have
a
resource,
or
information
Entry in the bundle - will have a resource, or information
must
be
a
resource
unless
there's
a
request
or
response
fullUrl cannot be a version specific reference
The
fullUrl
element
must
be
present
when
a
resource
is
present,
and
not
present
otherwise
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
Contains
a
collection
of
resources
Contains a collection of resources
entry.search
only
when
a
search
FullUrl must be unique in a bundle, or else entries with the same fullUrl must have different meta.versionId
total
only
when
a
search
or
history
entry.request only for some types of bundles
FullUrl
must
be
unique
in
a
bundle,
or
else
entries
with
the
same
fullUrl
must
have
different
meta.versionId
entry.response only for some types of bundles
entry.request
only
for
some
types
of
bundles
total only when a search or history
entry.response
only
for
some
types
of
bundles
entry.search only when a search
Entry
in
the
bundle
-
will
have
a
resource,
or
information
Entry in the bundle - will have a resource, or information
must
be
a
resource
unless
there's
a
request
or
response
fullUrl cannot be a version specific reference
The
fullUrl
element
must
be
present
when
a
resource
is
present,
and
not
present
otherwise
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
Why
an
entry
is
in
the
result
set
-
whether
it's
included
as
a
match
or
because
of
an
_include
requirement.
Why an entry is in the result set - whether it's included as a match or because of an _include requirement.
bdl-1
:
total
only
when
a
search
or
history
(xpath:
not(f:total)
or
(f:type/@value
=
'searchset')
or
(f:type/@value
=
'history')
: total only when a search or history (
expression :
total.empty() or (type = 'searchset') or (type = 'history')
)
bdl-2
:
entry.search
only
when
a
search
(xpath:
not(f:entry/f:search)
or
(f:type/@value
=
'searchset')
: entry.search only when a search (
expression :
entry.search.empty() or (type = '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')
: entry.request only for some types of bundles (
expression :
entry.request.empty() or type = 'batch' or type = 'transaction' or type = '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')
: entry.response only for some types of bundles (
expression :
entry.response.empty() or type = 'batch-response' or type = '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
: On Bundle.entry: must be a resource unless there's a request or response (
expression on Bundle.entry:
resource.exists() or request.exists() or response.exists()
)
bdl-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))
: On Bundle.entry: The fullUrl element must be present when a resource is present, and not present otherwise (
expression on Bundle.entry:
fullUrl.empty() xor resource.exists()
)
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
: FullUrl must be unique in a bundle, or else entries with the same fullUrl must have different meta.versionId (
expression :
entry.where(fullUrl).select(fullUrl&resource.meta.versionId).isDistinct()
)
6.7.3.3
bdl-8
: On Bundle.entry: fullUrl cannot be a version specific reference (
expression on Bundle.entry:
fullUrl.contains('/_history/').not()
Notes
)
2.35.3.3
Notes about Bundle Conceptually,
a
bundle
is
a
list
of
resources
with
some
context
(named
links,
and
status
on
the
entries)
Since
a
Bundle
is
itself
a
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
it has the same common metadata as all resources, including profile assertions, tags, and security labels
Although there are not extensions on the Bundle itself,
link
,
entry
, and
search
/
request
/
response
can all have extensions. See
Patient
and
Location
for examples on search
Both Bundle.link and Bundle.entry.link are defined to support providing additional context when bundles are used (e.g.
HATEOAS ).
Bundle.entry.link
corresponds
to
links
found
in
the
HTTP
header
if
the
resource
in
the
entry
was
). 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
directly. This specification defines some specific uses of Bundle.link for
searching
and
and
paging
,
but
no
specific
uses
for
Bundle.entry.link,
and
no
defined
function
in
a
transaction
-
meaning
is
implementation
specific
, 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
2.35.3.4
Using Bundles The
content
and
rules
for
using
a
Bundle
depend
on
the
6.7.3.4.3
Search
Results
2.35.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
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,
for further information.
6.7.3.4.4
History
2.35.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
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,
for further information.
6.7.3.4.5
Transaction
2.35.3.4.5
Transaction / Batch 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
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.
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.
6.7.3.4.6
Transaction
Response
2.35.3.4.6
Transaction/batch 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
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.
element which indicates the outcome of the HTTP operation that the server performed for the entry.
6.7.3.4.7
Collection
2.35.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.
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.
6.7.4
Resource
URL
&
Uniqueness
rules
in
a
bundle
2.35.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:
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?)
no duplicates (weird edge cases - change tracking?)
message
no
duplicates
(well,
messaging
deltas?)
no duplicates (well, messaging deltas?)
transaction
no
duplicates
allowed
no duplicates allowed
transaction-response
no
duplicates
allowed
no duplicates allowed
batch
no
duplicates
allowed
no duplicates allowed
batch-response
no
duplicates
allowed
no duplicates allowed
history
yes,
duplicates
are
allowed
yes, duplicates are allowed
searchset
no
duplicates
allowed
no duplicates allowed
collection
yes,
duplicates
are
allowed,
though
generally
would
not
be
a
good
idea
yes, duplicates are allowed, though generally would not be a good idea
6.7.4.1
Resolving
references
in
Bundles
2.35.4.1
Resolving references in Bundles The
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
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
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 not an absolute reference, convert it
If the fullUrl starts with urn:uuid: or urn:oid:, then treat then append the id to the base URL and try to resolve within the bundle as for a RESTful URL reference. If no resolution is possible, then the reference has no defined meaning within this specification
if the fullUrl of the resource that contains the reference 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
), extract the
[root]
, 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 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
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:
.
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"/>
<!-- 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 resource above -->
<reference value="http://example.org/fhir/Patient/1"/>
<!-- 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 patient immediately above -->
<!-- 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>
6.7.5
Search
Parameters
2.35.5
Search Parameters Search
parameters
for
this
resource.
The
common
parameters
also
apply.
See
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
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
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
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
Foundation
Bundle
type
link
link
resource
<!-- from Resource: id, meta, implicitRules, and language -->
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>
