PaceXHTMLIntrospection2

Abstract

Provide a simple introspection document in an XHTML format that is machine parsable, human readable and eliminates the need for a collection document.

Status: Proposed

Rationale

The introspection documents proposed thus far are not satisfactory. The old introspection format has shortcomings as noted in PaceXoXoIntrospection [1], from which this pace builds. Having a separate collection document is no longer necessary. Atom feed documents will provide collection membership so the layout and capabilities of collections can be specified all together, directly in the introspection document. This provides for a simple model of interaction.

GET introspection document.
POST entries or GET feeds of collection members
Normal Editing

PaceXoXoIntrospection is an excellent solution to providing this pattern but has two issues.

Metadata - Some WG members want to communicate "search-templates"

PaceXoXoIntrospection offers no way to do this.

Parsing - If providers want to include additional markup in their

problematic.For instance, they may want to list something in their description of a collection but do not intend that list to be interpreted as collections.

Additional metadata, safer easier parsing, and some added flexibility can be achieved by using an XMDP profile [3].

Proposal

The conceptual model being expressed is the same as XOXO in that collections can contain both entries and collections. Collections MAY have 0 or 1 primary feeds to which entries can be POSTed and from which the entries considered to be "in" the collection can be retrieved, 0 or many "search-templates", 0 or many "member-types" and 0 or many nested collections.

Though the approach described in this Pace can represent collections that contian collections and entries (via a feed), all three of the following models can be enforced by the server.

nestable collections that are containers
nestable containers that can contain collections
just a list of collections - no nesting

This Pace proposes to address the concerns in the Rationale above and add flexibility by using an XMDP profile.

1. Metadata

Metadata such as "search-templates" or "member-types" could be included using a combination of XHTML elements [4] but this would restrict the use of XHTML elements and make it easier to introduce ambiguities that could lead to the parsing problems discussed above.

Using class names and rel values to enhance introspection semantics allows us to include more metadata without these restrictions or risks.

2. Parsing

Class names and rel values can enhance XHTML semantics to clarify how the parser should interpret XHTML introspection documents. If a XOXO list structure is used to represent collections and a collection wants to include a list of "member-types" or just list the types of items it is intended for to human readers, the meaning of list elements would be unclear. Class names can be used to indicate which list items are actually collections.

This approach is often referred to as a microformat [5] though there is a bit more to the definition of a microformat.

Testimony as to parsability of this type of format can be found at the following URLs:

3. Flexibility

Since the parser is paying attention to only a very few specific arrangements of elements, class names and rel values, implementations will be free to create documents that meet their needs without running into problems. See the examples below.

XMDP Profile

This profile requires nothing. Note the plural options for some class names. The name "traversal" is used rather than "search-template".

<dl class="profile">
 <dt>class</dt>
 <dd>
   <p>
     <a rel="help"
        href="http://www.w3.org/TR/html401/struct/global.html#adef-class"
        >HTML4 definition of the 'class' attribute.</a>
     Class names and rel values in an XHTML document
     for Atom Publishing Protocol introspection
     can be interpreted according to this document.
     Everything is optional except for rel='entry' or 'generic'.
     A minimal case would be a document with an anchor or link
     with a rel='entry' or 'generic' in it.
     The Atom Publishing Protocol will be referred to as &quot;APP&quot;
     for the remainder of this document.
     This document should be peppered with references to the AtomPub spec.
     This document is for discussion purposes only.
   </p>
   <dl>
     <dt id="collection">collection</dt>
     <dd>
       A container for the class names and relations
       defined in the remainder of this document
       such that they describe an APP collection.
       This class can also contain itself recursively.
     </dd>
     <dt id="collections">collections</dt>
     <dd>
       All list items in a list of this class are of class collection.
       This class can also contain itself recursively.
     </dd>
     <dt id="collectionTitle">collectionTitle</dt>
     <dd>
       The title of an APP collection will be the title of the 
       XHTML anchor or link with rel='entry' or 'generic' pointing
       to the collection's primary feed.
       If these are not present then it will be the text of the 
       anchor (if it is an anchor).
       If these are not present then the contents of the 
       element within the collection (but not within a nested
       collection) with a class name of collectionTitle
       will be considered the name of the collection.
       If none of these exist, it is highest ranking heading element
       within the collection container. 
       If none of these exist, it is simply an unnamed collection. 
     </dd>
     <dt id="collectionDescription">collectionDescription</dt>
     <dd>
       A textual description of an APP collection.
       If this is not present,
       the text of the anchor with rel='entry' or 'generic'
       will be used.
     </dd>
     <dt id="traversal">traversal</dt>
     <dd>
       An APP "magic brackets" definition
       of how to traverse an APP collection.
       If this is not present
       the feed at the collection URI
       should indicate traversal.
     </dd>
     <dt id="traversals">traversals</dt>
     <dd>
       All items in a list of this class are of class traversal.
     </dd>
     <dt id="memberType">memberType</dt>
     <dd>
       A member type accepted by an APP collection.
     </dd>
     <dt id="memberTypes">memberTypes</dt>
     <dd>
       All items in a list of this type are of class memberType.
     </dd>
   </dl>
 </dd>
 <dt>rel</dt>
 <dd>
   <p>
     <a rel="help"
        href="http://www.w3.org/TR/html401/struct/links.html#adef-rel">
       HTML4 definition of the 'rel' attribute.</a>
   </p>
   <dl>
     <dt id="entry">entry</dt>
     <dd>
       Indicates that the referenced resource is a APP collection
       that accepts only atom entry resources.
       This is the only thing required to indicate a collection.
       if this appears inside one or more elements of class 
       'collection' then it indicated the URI of the inmost one.
     </dd>
     <dt id="generic">generic</dt>
     <dd>
       Indicates that the referenced resource is a APP collection
       that excepts resources and treats them as binary data.
       This is the only thing required to indicate a collection.
       if this appears inside one or more elements of class 
       'collection' then it indicated the URI of the inmost one.
     </dd>
   </dl>
 </dd>
</dl>

The XOXO microformat is recommended to provide structure to XHTML introspection documents.[6]

Examples: XHTML Introspection Documents might look something like the following.

The James Snell version (slightly modified):

<html>
<head>
 <link rel="entry" href="/entries" />
 <link rel="generic" href="/pics" />
 <link rel="entry" href="/categories" />
 <link rel="entry" href="/foo" />
 ...

The Robert Sayre version (slightly modified):

<ul class="xoxo collections">
  <li>
    <a href="/app/collection.py?id=1&amp;type=entries"
       rel="entry" type="application/atom+xml">Main Blog</a>
       <ul class="collections">
         <li><a href="/app/collection.py?id=2&amp;type=generic"
                rel="generic" type="application/atom+xml">My Stuff2</a>
         </li>
       </ul>
  </li>
  <li>
    <a href="/app/collection.py?id=3&amp;type=entries"
       rel="entry" type="application/atom+xml">Side Bar Blog</a>
       <ul class="collections">
         <li><a href="/app/collection.py?id=4&amp;type=generic"
                rel="generic" type="application/atom+xml">My Stuff4</a>
         </li>
       </ul>
  </li>
  <li>
     <a href="/app/collection.py?id=5&amp;type=entries"
        rel="entry" type="application/atom+xml">A Third Blog</a>
        <ul class="collections">
          <li>
            <a href="/app/collection.py?id=6&amp;type=generic"
               rel="generic" type="application/atom+xml">My Stuff6</a>
          </li>
        </ul>
  </li>
</ul>

With more metadata:

<ul class="xoxo collections">
  <li>
    <a href="/app/collection.py?id=1&amp;type=entries"
       rel="entry" type="application/atom+xml">Main Blog</a>
    <ul class="memberTypes">
      <li>hCal</li>
      <li>hCard</li>
    </ul>
    <ul class="traversals">
      <li>/app/collection.py?id=1&amp;type=entries&amp;index={index}</li>
      <li>/app/collection.py?id=1&amp;type=entries&amp;date={daterange}</li>
    </ul>
    <ul class="collections">
      <li><a href="/app/collection.py?id=2&amp;type=generic"
             rel="generic" type="application/atom+xml">My Stuff2</a>
       </li>
    </ul>
  </li>
</ul>

Impacts

Notes

References

CategoryProposals