UserPreferences

PaceReworkIntrospection


Abstract

Streamline the existing Introspection document format

Status

Proposal

Rationale

Simplification. Allowing the <collection> element to appear outside <workspace> simplifies the really-simple cases. media-type as an element doesn't make sense given that there's only one of 'em. Changing to attribute simplifies the document.

Improved deterministic selection. Changing media-type value from 'media' to "mediaType | mediaRange" increases the granularity of metadata on the collection allowing clients to deterministically select media collections appropriate for specific media types.

Indication of Preferred collection. Specifying that the order of collections in the workspace allows indication of a default or "preferred" collection for the workspace.

Proposal

Replace the current -06 Sections 7.2 and 7.3 with the following:

#.  Element Definitions

#.1.  The 'app:introspection' Element

   The 'app:introspection' Element is the root of APP Introspection
   Documents.

     appIntrospection =
       element app:introspection {
         atomCommonAttributes,
         ( appWorkspace*,
         & appCollection*,
         & extensionElement* )
       }

   This specification assigns no significance to the order of the child
   elements of 'app:introspection'.

#.2.  The 'app:workspace' Element

   The 'app:workspace' Element represents a logical collection of
   related APP Collections.

     appWorkspace =
       element app:workspace {
         atomCommonAttributes,
         & attribute title (text),
         ( appCollection*,
           & extensionElement )
       }

   The 'title' attribute specifies a human-readable, language-sensitive
   label for the workspace.

   The order of 'app:collection' elements is significant. The first element 
   SHOULD refer to the preferred or primary collection.

#.3.  The 'app:collection' Element

   The 'app:collection' Element represents a collection resource as
   specified by the Atom Publishing Protocol.

     appCollection =
       element app:collection {
         atomCommonAttributes,
         & attribute title (text),
         & attribute href (IRI),
         & attribute type ( 'entry' | extensionType )?,
         ( extensionElement )
       }

     extensionType = ( NMTOKEN | mediaType | mediaRange )

   The 'title' attribute specifies a human-readable, language-sensitive
   label for the collection.

   The 'href' attribute specifies the IRI of an APP collection resource.

   The 'type' attribute MAY be used to specify the types of resources
   contained by the collection.  A value of 'entry' indicates that the
   collection membership consists entirely of Atom Entry Documents.  If
   the collection element does not contain a 'type' attribute, the
   membership of the collection SHOULD be considered to be
   unconstrained.  If the value specified is a media type or media
   range, the membership of the collection SHOULD be considered to be
   constrained to resources of the specified type or covered by the
   specified range.  If the 'type' attribute specifies a value that is
   not understood by the an application, the application MUST ignore the
   attribute as if the attribute were not present.

Example

   Simple Example

   <?xml version="1.0" ?>
   <app:introspection
     xmlns:app="http://www.w3.org/2005/Atom-Introspection">
    <app:collection
     title="Bookmarks"
     type="entry"
     href="http://example.com/bookmarks" />
    <app:collection
     title="Photos"
     href="http://example.com/photos" />
   </app:introspection>

   Workspace Example

   <?xml version="1.0" ?>
   <app:introspection
     xmlns:app="http://www.w3.org/2005/Atom-Introspection">
    <app:workspace title="My Weblog">
     <app:collection
      title="Entries"
      type="entry"
      href="http://myblog.example.com/entries" />
     <app:collection
      title="Photos"
      type="image/*"
      href="http://myblog.example.com/photos" />
     <app:collection
      title="Files"
      href="http://myblog.example.com/files" />
    </app:workspace>
   </app:introspection>

Impacts

Notes


CategoryProposals