This page is part of the FHIR Specification (v0.06: DSTU 1 Ballot 2). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions

Atom Feeds 2.6

One common operation performed with resources is to gather a collection of resources into a single XML instance. In FHIR this is referred to as "bundling" the resources together. The resource bundle is not just a list of references to resources, but includes their whole content. 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
• Returning a set of versions of resources as part of the history operation on a server
• Storing a collection of resources
• Exchanging a set of resources as part of a message transaction
• Grouping a self-contained set of resources to act as an exchangeable and persistable group with clinical integrity (i.e. a clinical document)

Whenever resources are gathered into a collection, this is done using the Atom format (http://tools.ietf.org/html/rfc4287), following this template:

<feed xmlns="http://www.w3.org/2005/Atom">
  <title><!-- 1..1 string Text statement of purpose --></title>
  <updated><!-- 1..1 instant When the bundle was built --></updated>
  <id><!-- 1..1 uri Unique uri for this bundle --></id>
  <link rel="self" href="[building application url]"><!-- 0..1 --></link>

  <entry><!-- Zero+ -->
    <title><!-- 1..1 string Text summary of resource --></title>
    <link rel="self" href="Version Specific reference to Resource"><!-- 0..1 --></link>
    <id><!-- 1..1 uri Logical Id (uri) for this resource --></id>
    <updated><!-- 1..1 instant Last Updated for resource --></updated>
    <published><!-- 0..1 instant Time resource copied into the feed --></published>
    <author><!-- Who created resource? -->
      <name><!-- 1..1 string Name of Human or Device that authored the resource --></name>
      <uri><!-- 0..1 uri Link to the resource for the author --></uri>
    </author>
    <category term="[Resource Type]" scheme="http://hl7.org/fhir/resource-types"><!-- 1..1 --></category>  
    <content type="text/xml"><!-- 1..1 -->
      <[ResourceName] xmlns="http://hl7.org/fhir">
        <!-- Content for the resource -->
      </[ResourceName]>
    </content>
    <summary type="xhtml"><!-- 0..1 -->
      <div xmlns="http://www.w3.org/1999/xhtml"><!-- Narrative from resource --></div>
    </summary>
  </entry>
  <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
    <!-- 0..1 Enveloped Digital Signature (see Atom section 5.1) -->
  </Signature>
</feed>

Notes 2.6.1

• Logically, a bundle is a set of resources that are prepared to send somewhere for consumption - a "feed". There is no implication that the feed is a standing arrangement (though this is not precluded)
• The order of elements does not matter in an atom feed. The order of elements in the atom namespace as documented here does not need to be followed
• The title for the feed and the entry are arbitrary human readable content and not to be used for any automated processing. Applications may populate these in any useful way
• Every bundle must have a unique id and that id must be a valid absolute uri. UUIDs are recommended (urn:uuid:...)
• The feed.link element is assigned no particular meaning the FHIR specification, but may be used to provide a reference to the source of the feed
• The entry element carries the three pieces of resource metadata: Id (.id), Version Id (.link), Last Updated (.updated)
• The entry.id must be an absolute url, the tail element of which is the logical id of the resource
• The entry.link is a version specific reference to the resource. It must be present unless the resource has no established identity (see comments under RESTful batch Operation).
• When used in a RESTful implementation, the entry.link and entry.id are the URLs of the resource on the system; the version specific link can be used as the basis synchronizing pub/sub systems using the atom bundle with the updates operation. In other contexts, the values should be literal references to a server if one is available
• Author is a required element by the atom element. The author of a resource is not explicit in the FHIR resource model; instead it is delegated to the infrastructure. The name is the name of a human author or a device. The uri is a link to the resource for the author
• An xml:base element may be specified on the content element, though one is not needed for FHIR resources.
• The entire bundle can be signed with a single Enveloped Digital Signature as described in the Atom specification (section 5.1). See below for further comment

Bundling versions - deletion 2.6.2

When returning a set of resources or versions of a resource, an entry might indicate that the entry has been deleted. Deleted resources are represented in an atom feed as defined by rfc6721.txt:

<feed xmlns="http://www.w3.org/2005/Atom">
  ... feed elements and other entries ...
  <at:deleted-entry xmlns:at="http://purl.org/atompub/tombstones/1.0"
      ref="[Logical Id for deleted resource]" when="instant [when deleted]">
    <link rel="self" href="[Version Specific reference to Resource]"><!-- 0..1 --></link>
  </at:deleted-entry>
  ... other entries ...

A deleted resource returns a 410 error if it is accessed through the RESTful interface.

Binary Resources 2.6.3

There are situations where it is useful or required to represent binary resources in the bundle. These are resources that are referred to from FHIR Resources (usually via a URI) where it is convenient to include these in the feed directly rather than leaving them by reference.

When binary resources are represented in the feed, they are enclosed as base64 encoded content along with a content-type, which is the mime-type as it would be specified in HTTP:

  ...
  <entry>
    ...
    <category term="Binary" scheme="http://hl7.org/fhir/resource-types"><!-- 1..1 --></category>
    <content type="text/xml"><!-- 1..1 -->
      <Binary xmlns="http://hl7.org/fhir" contentType="[mime type]">[Base64 Content]</Binary>
    </content>
    <summary type="xhtml"><!-- 0..1 -->
      <div xmlns="http://www.w3.org/1999/xhtml">Binary resource</div>
    </summary>
  </entry>
  ...

The summary should be some equivalent to "Binary Resource" in an appropriate language.

Resolving references to Resources 2.6.4

Readers of the resources bundles should always look through the resources in the atom feed when a resource reference is encountered. The resource reference may have the resource type and a relative url, which is the id of the target, like this:

  <institution>
    <type>Organization</type>
    <id>23</id>
  </institution>

A reader trying to find the resource this institution element identifies should always look through the entries in the atom feed prior to looking anywhere else for the institution. If that organization is in the feed, it would look like this:

   .. feed ..
  <entry>
    .. 
    <id>http://acme.com/fhir/organization/@23<id>
    .. 
    <category term="Organization" scheme="http://hl7.org/fhir/resource-types"/>

    <content type="text/xml">
      <Organization xmlns="http://hl7.org/fhir">
         <!-- other Content for the resource -->
      </Organization>
    </content>
  ... feed ...

It would also be possible to locate the resource by an absolute url. In this case, the id element contains a reference to the location of the resource:

  <institution>
    <type>Organization</type>
    <id>http://acme.com/fhir/organization/@23</id>
  </institution>

If there is no resource in the atom feed with an appropriate URL, then the application may try accessing the provided URL directly or use some other implementation-specific method for resolving how to find the resource. Note that this example used a FHIR RESTful URL, but this is not required.

Implementation Notes 2.6.5

• Atom Feeds may be signed following the rules described in the Atom specification. One consequence of signing the document is that URLs, Identifiers and internal references are frozen and cannot be changed. This might be a desired feature, but it may also cripple interoperability between closed eco-systems where re-identification frequently occurs. For this reason, it is recommended that only Document Bundles are signed and then only when all the related resources are found in the bundle.
• FHIR resources make use of id attributes as targets for internal references with resources. These id attributes are unique and resolved within the context of a single resource. When resources are combined into a bundle, different resources may contain duplicate id attributes. Thus it is important to limit the scope of resolution of an id attribute to the resource in which the id attribute is declared.
• When representing the atom feed as JSON, use the method described here.
• The Document framework defines an additional RESTful end-point that works like a normal RESTful interface but serves document bundles instead of document resources.

This is an old version of FHIR retained for archive purposes. Do not use for anything else
Implementers are welcome to experiment with the content defined here, but should note that the contents are subject to change without prior notice.
© HL7.org 2011 - 2012. FHIR v0.06 generated on Tue, Dec 4, 2012 00:04+1100. License