This document proposes that an APP service should expose its managed collections to an APP client using an Atom Feed document containing entries that represent exposed Collections. It seeks to a) minimize invention by not defining a new XML document structure for introspection data, and b) allow for maximum flexibility based upon existing core Atom syntax extensibility.

I propose this is the simplest thing that could possibly work, but leaves plenty of room for rich use cases (like nested hierarchies of Collections) and/or domain-specific introspection metadata.

Author: Kyle Marvin




The Atom Syntax Spec Introduction states "Atom is an XML-based document format that describes lists of related information known as "feeds". Feeds are composed of a number of items, known as "entries", each with an extensible set of attached metadata."

This is a completely suitable abstraction model for exposing Atom Collections to APP clients. It is minimal invention to use it as such. If an Atom Feed is not suitable for representing Collections and a custom XML format is better suited to represent them, then to some degree it calls into question the overall suitability of the Atom content model. If we (the APP WG) won't use it for a potential use case without strong justification against, why do we expect a wide variety of content publishers to do so?

The core Atom Syntax already contains many supporting abstractions (like title, summary, author, contributor, updated, publishd, rights, source, or category [um, all of them?]) that are completely suitable and valid metadata that could be used to describe a collection and/or groups of collections. There is no need to reinvent these concepts in some other XML document format.

Using a single representation (Atom feeds) to represent a list of collections and a list of member resources reduces the number of concepts and code required to implement an APP client.


The following changes are proposed to draft-ietf-atompub-protocol-06:

REMOVE the following text from Section 2 (Notational Conventions):

Note: The Introspection Document allows the use of IRIs [RFC3987], as well as URIs [RFC3986]. Every URI is an IRI, so any URI can be used where an IRI is needed. How to map an IRI to a URI is specified in Section 3.1 of Internationalized Resource Identifiers (IRIs) [RFC3987].

REPLACE the following sentence in Chapter 3 (Terminology):

introspection document - A document that describes the location and capabilities of one or more collections. See Section 7


introspection feed document - An Atom feed that describes the location and capabilities of one or more collections. See Section 7

REPLACE the following text in Section 4 (Protocol Model):

The introspection document contains the IRIs of one or more collections.


The introspection feed document contains entries that refer to collections or to other introspection feed documents that represent nested collections.

REPLACE the entire Section 5.1 (Retrieving an Introspection Document) with:

5.1 Retrieving an Introspection Feed Document

Client                                   Server 
  |                                           |
  |  1.) GET to IRI of Introspection Feed     |     
  |                                           |     
  |  2.) Introspection Feed Document          |    
  |                                           |

The client sends a GET request to the IRI of the introspection feed document. The server responds with the introspection feed with entries that describe all of the collections, and the capabilities of those collections, that the service supports.

REPLACE the entire Section 7.0 with the following text:

7.0 Introspection

For authoring to commence, a client needs to first discover the capabilities and locations of collections offered. This is done using Introspection Feeds, which describe a server-defined grouping of Atom Collections.

An Introspection Feed Document MUST BE a valid Atom Feed Document with some additional constraints:

These constraints are:

* Every <atom:entry> element in the Introspection Feed Document MUST contain an <atom:content> child element with a src attribute (out of line content) and a type attribute with a value of 'application/atom+xml'.

* The IRI specified as the value of each src attribute MUST refer to a valid Atom Feed document. This feed document MAY be an Introspection Feed Document, if nested collections are supported by the service.

REMOVE the entire contents of Section 14 (IANA Considerations) that describe the Atom Introspection Document format


Here is a sample introspection feed, based upon the draft-06 example (including sample extension elements not within the scope of this PACE):

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns=''>
  <link href='/'>
  <title>My Service Collections</title> 
    <name>Kyle Marvin</name>

    <title>My Blog Entries</title>
    <content src='' type='application/atom+xml'>
    <summary>My mainline blog entries<summary>
    <category>Main Blog</category>
    <content src='' type='application/atom+xml'>
    <summary>Pictures I reference from my blog<summary>
    <title>Remaindered Links</title>
    <content src='' type='application/atom+xml'>
    <summary>Other random links for my sidebar<summary>



This PACE does not describe any metadata extensions associated with an Atom entry describing an Atom collection, such as list templates or member types. There are a number of in-flight PACEs proposing removal or alteration of these elements from the existing Introspection model. A companion PACE (to this one) can be written that defines the APP extension elements that are part of the core, pending dispensation of the various removal or change PACEs against draft-06. This IntrospectionEntryExtension PACE could add additional constraints to the ones proposed in the revised Section 7.

This should be a relatively trivial exercise; for example, the existing elements (member-type and list-template described in draft-06 (section 7.3.4/7.3.5) could be brought over verbatim as children of a collection entry to achieve parity with draft-06 with respect to collection metadata.

This PACE removes the concept of Workspaces from draft-06. This can be implemented by using either a nested hierarchy of collections or the judicious use of the <atom:category> elements for grouping (if flat). This can be defined by a companion PACE if it is believe to be critical functionality for the APP core, but my proposal leaves it unspecified.


* Removes a significant number of concepts (and text) related to introspection from the APP core.