This page is part of the FHIR Specification (v0.05: DSTU 1 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

Atom Feeds

One basic operation performed with resources is to gather all a list of resources into a single XML document. 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
• Storing a list 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 gethered into a list, this is done using the Atom format (http://tools.ietf.org/html/rfc4287), following this template:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:gd="http://schemas.google.com/g/2005">
  <title 1..1 type="string">text statement of purpose</title>
  <updated 1..1 type="instant">when the bundle was built</updated>
  <id 1..1 type="uri">unique uri for this bundle</id>
  <link 1..1 rel="self" href="[building application url]"/>

  <entry gd:etag="version id">    <!-- Zero+ -->
    <title 1..1 type="string">text summary of resource</title>
    <link 1..1 rel="self" href="Master Location for Resource"/>
    <id 1..1 type="uri">Master Id (uri) for this resource</id>
    <updated 1..1 type="instant">Last Updated for resource</updated>
    <published 0..1 type="instant">Time resource copied into the feed</updated>
    <author>
      <name 1..1 type="string">Name of Human or Device that authored the resource</name>
      <uri 0..1 type="uri">Link to the resource for the author</uri>
    </author>
    <category 1..1 term="[Resource Type]" scheme="http://hl7.org/fhir/sid/fhir/resource-types"/>  
    <content 1..1 type="text/xml">
      <[ResourceName] xmlns="http://hl7.org/fhir">
         <id 1..1 type="id">Resource Id (i.e. normal resource content)</id>
         <!-- Content for the resource -->
      </[ResourceName]>
    </content>
    <summary 0..1 type="xhtml">
        <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:

• 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 arbitary 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 id. UUIDs are recommended
• The link elements are mandatory in the atom feed format.
• The type attribute on the content element does appear in the xml instance (it's an atom type, not a FHIR type)
• The entry element carries the three pieces of resource metadata: Version Id, Last Updated, and Master Location
• 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
• In a RESTful implementation, the Master Location is the URL of the resource on a system that is the master for that resource. In the absence of a known master or a RESTful implementation, some other location may be used.
• 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. See below for further comment

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>1145c09c-73d0-4297-9835-620e4afa9deb</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>1145c09c-73d0-4297-9835-620e4afa9deb<id>
    .. 
    <category term="Organization" scheme="http://hl7.org/fhir/sid/fhir/resource-types"/>

    <content type="text/xml">
      <Organization xmlns="http://hl7.org/fhir">
         <id>1145c09c-73d0-4297-9835-620e4afa9deb</id>
         <!-- other Content for the resource -->
      </Organization>
    </content>
  ... feed ...

It would also be possible to locate the resouce 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/patient/@23</id>
  </institution>

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

   .. feed ..
  <entry>
    .. 
    <link rel="self" href="http://acme.com/fhir/patient/@23"/>
    <id>23<id>
    .. 
    <category term="Patient" scheme="http://hl7.org/fhir/sid/fhir/resource-types"/>

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

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

• 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 good 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 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.05 generated on Sun, Sep 9, 2012 03:28+1000. License