UserPreferences

PaceAPPCategories


Abstract

Regarding Draft protocol-09

Status

In play

Rationale

A simple way for clients to list the categories available

Proposal

Insert a new section "Categories Documents" after section 6; thus Section 7. "Introspection Documents" becomes section 8 and everything else moves up.

7. Categories Documents

Categories Documents contain lists of categories specified using the "category" element from the Atom Syndication Format [RFC4287].

Categories documents are identified with the "application/app+xml" media type (see Section 14).

7.1 Example

<?xml version="1.0" ?>
<app:categories 
 xmlns:app="http://purl.org/atom/app#" xmlns="http://www.w3.org/2005/Atom" 
 fixed="yes" scheme="http://example.com/cats/big3">
  <category term="animal" />
  <category term="vegetable" />
  <category term="mineral" />
</categories>

This Categories document contains three categories with terms "animal", "vegetable", and "mineral". None has a category label (in the RFC4287 sense). They all share the "http://example.com/cats/big3" category scheme (in the RFC4287 sense); that is to say, if the "mineral" category were to appear in an Atom Entry or Feed Document, it would appear as

<category scheme="http://example.com/cats/big3" term="mineral" />

7.2 Element Definitions

7.2.1 The "app:categories" element

The root of a Categories Document is the "app:categories" element. An "app:categories" element MAY contain one or more "category" elements in the Atom namespace, http://www.w3.org/2005/Atom, as children.

7.2.2 Attributes of "app:categories"

An "app:categories" element which is the root of a Categories Document differs from one appearing in an Introspection document in that it MUST NOT have an "href" attribute. Also, it MAY have a "scheme" attribute, which provides a default value for any contained "atom:category" elements that do not themselves have a "scheme" attribute.

It may have a "fixed" attribute, as specified the definition of the app:categories element in section 8.2.5.

(RNC fragment to be provided.)

7.2.3 Extensibility

The "app:categories" element may contain child elements other than "atom:category", and attributes other than those described in this section. Furthermore, the child "atom:category" elements may contain child elements or attributes other than those described in [RFC4287]. This specification assigns no meaning to such "foreign markup".

Software agents processing Categories Documents MUST NOT stop processing or signal an error or change their behavior as a result of encountering such foreign markup, and SHOULD preserve it when transmitting such documents.

Enhance the Example section, formerly 7.1

8.1 Example

<?xml version="1.0" encoding='utf-8'?>
<service xmlns="http://purl.org/atom/app#">
  <workspace title="Main Site" > 
    <collection 
      title="My Blog Entries" 
      href="http://example.org/reilly/main" >
      <member-type>entry</member-type>
      <categories fixed="yes" href="http://example.org/cats/forMain.cats" />
    </collection>
    <collection 
      title="Pictures" 
      href="http://example.org/reilly/pic" >
      <member-type>media</member-type>
    </collection>
  </workspace>
  <workspace title="Side Bar Blog">
    <collection title="Remaindered Links" 
      href="http://example.org/reilly/list" >
      <member-type>entry</member-type>
      <categories fixed="yes" href="http://example.org/cats/forMain.cats" />
      <categories fixed="no">
        <atom:category 
          scheme="http://example.org/extra-cats/" 
          term="joke" />
        <atom:category 
          scheme="http://example.org/extra-cats/" 
          term="serious" />
      </categories>
    </collection>
  </workspace>
</service>

This Introspection Document describes two workspaces. The first, called "Main Site", has two collections called "My Blog Entries" and "Pictures" whose IRIs are "http://example.org/reilly/main" and "http://example.org/reilly/pic" respectively. The "Pictures" includes an accept element indicating that client can post image files to the collection to create new entries. Entries with associated media resources are discussed in section 8.3.

The second workspace is called "Side Bar Blog" and has a single collection called "Remaindered Links" whose collection IRI is "http://example.org/reilly/list".

Within each of the two entry collections, the categories element provides a listing of available categories for member entries. In the "My Blog Entries" collection, the list of available categories is a closed set, signaling a request from the server that entries be posted only with categories selected from those listed. The "Side Bar Blog" collection provides the same list, but offers two extra categories as well, provided locally within the Introspection Document.

8.2.3 The "app:collection" Element

The "app:collection" describes a collection. The app:collection element MUST contain one app:member-type element and MAY contain any number of app:categories element.

appCollection =  
  element app:collection {
    appCommonAttributes,
    attribute title { text },
    attribute href { text },
    ( appMemberType,
     & appCategories*
     & extensionElement* )
  }

8.2.5

The "app:categories" element provides a listing of what categories may be applied to the members of a collection.

appInlineCategories =
    element app:categories {
      attribute fixed { 'yes' | 'no' }?,
      (atomCategory*)
    }

  appOutOfLineCategories = 
    element app:categories {
      attribute fixed { 'yes' | 'no' }?,
      attribute href { atomURI },
      (empty)
    }

  appCategories = appInlineCategories | appOutOfLineCategories

The app:categories element MAY contain a "fixed" attribute, with a value of either "yes" or "no", indicating whether or not the listing of categories is considered to be a fixed, or closed set. Collections that indicate a fixed set MAY reject members that include categories not specified in the provided listing. Collections that indicate an open set SHOULD NOT reject otherwise acceptable members that include categories that are not specified in the provided listing.

The app:categories element MAY contain a "href" attribute, whose value MUST be an IRI reference identifying a Categories Document. If the "href" attribute is provided, app:categories MUST be empty.

Impacts

Notes


CategoryProposals