UserPreferences

PaceCollectionSyntax


Abstract

A generic syntax for all the collections managed by the Atom Publishing Protocol.

Status

Open

Rationale

There are several types of collections that need to be managed by the APP, including entries, users, templates, and simple resources. Having a consistent format for enumerating the contents of such collections will make implementing clients and servers easier.

Proposal

Create a new section in the publishing protocol describing the Collection Document. Note that this is following the form outlined in PaceProblemStatements.

N. The Collection Document

Problem Statement

There are several types of collections that need to be managed by the APP, including entries, users, templates, and simple resources. Having a consistent format for enumerating the contents of such collections will make implementing clients and servers easier.

Normative Text

The Collection Document is a representation of a Collection Resource. It is a simple list of the URIs of Member Resources and an accompanying human readable text description. The Collection Document may not contain all the resources in the collection. If there are additional resources to be enumerated then an optional atom:next child element may be present which points to another Collection Document. The process of listing some resources and pointing to a further collection document may be repeated as many times as needed to enumerate all the resources in a Collection.

Here is an example Collection Document:

<?xml version="1.0" encoding='utf-8'?>
<collection xmlns="http://www.purl.org...">
  <next href="http://example.org/collections/sort.cgi?dir=datedown&next=5"/>
  <resource href="http://example.org/news/5">Human Readable Info 1</resource >
  <resource href="http://example.org/news/4">Human Readable Info 2</resource >
  <resource href="http://example.org/news/3">Human Readable Info 3</resource >
  <resource href="http://example.org/news/2">Human Readable Info 4</resource >
</collection>

N.1 atom:collection

The "atom:collection" element is the document element for Collection Documents. The first element child MAY be atom:next, which MAY be followed by one or more atom:resource child elements.

N.2 atom:resource

There is one atom:resource element for each resource in the Collection, that is, after enumerating all the resources in the Collection each resource SHOULD only be listed once. The atom:resource element contains human readable text that describes the resource whose URI is given in the 'href' attribute. The content of the atom:resource construct MUST NOT contain child elements. Such text is intended to be presented to humans in a readable fashion.

N.2.1 The atom:resource 'href' Attribute

Each atom:resource element MUST contain a single 'href' attribute which contains the URI of the resource.

N.3 atom:next

If present, this element indicates a the URI of another Collection Document that enumerates more resources in the Collection.

N.3.1 The atom:next 'href' Attribute

Each atom:next element MUST contain a single 'href' attribute which contains the URI of further Collection Documents that describe the Collection. Iteratively dereferencing the 'href' attributes of atom:next elements will let a client completely enumerate all the members of a collection. The atom:next element must be empty.

Design Rationale

This is a simple format that allows enumerating resources. The file size can be determined by the server and the files themselves can even be stored as static XML files, making it very fast to serve them to clients and also enjoying all the speed improvements available via GET (for example ETags and compression).

Impacts

The FeedURI section of the protocol spec must also be updated to indicate that the representation is no longer a feed but a Collection Document.

Notes

The collection document does not need to be so simple. There are enhancements that can be made. A more advanced collection that points to further collections with different sort orders and subsets. A subset is just again another collection but with a subset of the original collections resources.

'Ordering' points to a specific ordering of the current subset (which is again a collection).

'Subset' points to a subset of the current collection.

<?xml version="1.0" encoding='utf-8'?>
<collection xmlns="http://www.purl.org/...">
  <ordering href="http://example.org/collections/sort.cgi?dir=up">All Sorted Alphabetically</next>
  <ordering href="http://example.org/collections/sort.cgi?dir=dateup">All Sorted By Date (Ascending)</next>
  <subset href="http://example.org/collections/sort.cgi?dir=datedown">All Sorted By Date (Descending)</next>
  <next href="http://example.org/collections/sort.cgi?dir=datedown&next=5"/>
  <resource href="http://example.org/news/5">Human Readable Info 1</resource>
  <resource href="http://example.org/news/4">Human Readable Info 2</resource>
  <resource href="http://example.org/news/3">Human Readable Info 3</resource>
  <resource href="http://example.org/news/2">Human Readable Info 4</resource>
</collection>

Add verbage to a best practices document that says that using indices is not a good idea. I.e. if the elements are ordered and removing the first one renumbers all the rest then that would be bad.

A sub-proposal is to impose the WebDAV containment relation on the <subset> URIs. This is the requirement that members of the collection /foo have names like /foo/bar and /foo/baz.


See Also: PaceOrderedCollections


CategoryProposals