This page is part of the FHIR Specification (v0.01: Historical Archive Draft). The current version which supercedes this version is 4.0.1. For a full list of available versions, see the Directory of published versions

# Aggregation

One basic operation performed with resources is to aggregate a group of resources into a single XML document. This is performed in many of the implementation frameworks. Aggregated resources are useful for grouping resources together for a variety of different reasons, including:

- Listing a set of resources that have changed since a given instant in time
- Exchanging a set of resources as a single batch
- Grouping a self contained set of resources to act as an exchangeable and persistable group with clinical integrity (i.e. a clinical document)

Resources are aggregated 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 mand type="string">text statement of purpose</title>
      <updated mand type="dateTime">when aggregation happened</updated>
      <id mand type="id">unique id for this aggregation</id>
      <link mand rel="via" href="aggregating application url"/>

      <entry gd:etag="version id">    <!-- Zero+ -->
        <title mand type="string">text summary of resource</title>
        <link mand rel="self" href="Master Location for Resource"/>
        <id mand type="id">Master Id for this resource</id>
        <updated mand type="dateTime">Last Updated for resource</updated>
        <published opt type="dateTime">Time resource sourced for aggregation</updated>
        <author>
          <name mand type="string">Name of Human or Device that authored the resource</name>
          <uri opt type="uri">Link to the resource for the author</uri>
        </author>
        <category term="[Resource Type]" scheme="urn:hl7-org:sid/fhir/resource-types"/>
        <content mand type="text/xml">
          <[ResourceName] xmlns="http://www.hl7.org/fhir">
             <id mand type="id">Resource Id (i.e. normal resource content)</id>
             <!-- Content for the resource -->
          </[ResourceName]>
        </content>
        <summary opt type="xhtml">
             <!-- Narrative from resource for a browser. Must be wrapped in a <div> -->
        </summary>
        <Signature xmlns="http://www.w3.org/2000/09/xmldsig#" opt>
             <!-- Enveloped Digital Signature (see Atom section 5.1) -->
        </Signature>
      </entry>
    </feed>

Notes:

- Logically, an aggregation 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 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 aggregation must have a unique id, which 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 aggregation can be signed with a single Enveloped Digital Signature as described in the Atom specification

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

      <institution>
        <type>Organization</type>
        <id>1145c09c-73d0-4297-9835-620e4afa9deb</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 organization is in the feed, it would look like this:

       .. feed ..
      <entry>
        ..
        <id>1145c09c-73d0-4297-9835-620e4afa9deb<id>
        ..
        <category term="Organization" scheme="urn:hl7-org:sid/fhir/resource-types"/>

        <content type="text/xml">
          <Organization xmlns="http://www.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 the url (todo: explanation of this method).

## XML Ids in resources

FHIR resources make use of XML id attributes as targets for pointers elsewhere in the document. XML id attributes must be unique in the context of a single XML document, and the atom feed is a single XML document. it can be difficult and time consuming - or impossible in the presence of a digital signature - to fix the id attributes so they are unique when aggregating resources. For this reason, it is highly recommended that all XML id attributes are prefixed with the type and master id of the resource, like this: [Type]_[master id]_id (e.g. Person_23442_1).

## JSON Format

For the same reasons as resources, it is useful to define a standard JSON representation of the atom format. Several existing JSON representations of the atom feed are in general use; this specification adopts the Google GData representation.

> Note: All of the existing JSON representations of Atom are lacking in simplicity. The Google conversion is at least algorithmic.

## RESTful support for Aggregations

The standard RESTful endpoints (such as [baseurl]/people/#{id}.xml for a Person resource, or [baseurl]/documents/#{id}.xml) handle the individual resources, and not aggregations (though, per the restful spec, they may serve up aggregations for the history and update operations). There is a special end-point for aggregations at the relative url "/assemblies", which supports the following operations:

Instance |
read | Retrieve an aggregation
vread | Not supported - aggregations have no version history
update | Not supported - aggregations never change
delete | Delete an aggregation
validate | Check that the content would be acceptable as an update
history | Not supported - aggregations never change
transaction | Not supported
Manager
search | Search the aggregations based on some filter criteria. Supported search parameters Document.id - an id of a document. There should only be one aggregation for each document (optional, for systems that support documents) Message.id - an id of a message. There is usually only one aggregation per message. (optional, for systems that archive messages and make them available in this fashion) [ResourceType].id - an id of a resource that may be brought into an aggregation. Multiple aggregations should be expected in the response. (also optional)
create | Create an aggregation (i.e. post to the server. The ID is assigned by the client)
updates | Get a list of updates to resources of this type, optionally with some filter criteria
transaction | Not supported
conformance | Not supported (no conformance statement for aggregations directly)
schema | Not supported (no schema for FHIR atom directly)

For all these resources, the id (as used in the RESTful transactions) is the unique id of the aggregation. Note that creating an aggregation does not mean that any apparent implied transactions in the resources found in the aggregation should be applied to the server resources and/or executed by any system - specific transaction are required, either using the RESTful or messaging frameworks, or a SOA implementation.

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.01 generated on Mon, May 14, 2012 09:48+1000.