UserPreferences

PaceAppDocuments2


Abstract

Status

Withdrawn

Rationale

The document and element definitions in the current draft are stylistically inconsistent with those in the Atom Syndication Format. Further, the current spec defines two different versions of the app:collection element. This proposal refactors the definitions of the documents and elements in a way that is consistent with the style of the Atom syntax spec and in a way that merges the two app:collection definitions.

Introspection documents are still separate from Collection documents...

For example...

An Introspection Document

<service xmlns="...">
  <workspace xml:lang="en" title="My Workspace">
    <collection 
      title="My Entries" 
      type="entries" 
      href="http://www.example.com/myentries" />
    <collection 
      title="My Images" 
      type="generic" 
      mediatype="image/*"
      href="http://www.example.com/myimages" />
  </workspace>
</service>

A Collection Document

<collection xmlns="..." 
            title="My Entries"
            type="entries"
            xml:base="http://www.example.com/myentries"
            href="">
  <member href="http://www.example.com/myentries/1"
          updated="2005-12-12T12:12:12Z" />
  <member href="http://www.example.com/myentries/2"
          updated="2005-12-12T12:12:12Z" />
</collection>

Proposal

(refactor sections 5 and 8 to the following)

4.1 Atom Publishing Protocol Element Definitions

4.1.1 Container Elements

4.1.1.1 The "app:service" Element

  appService = 
    element app:service {
      appCommonAttributes,
      (appWorkspace*
       & undefinedContent)
    }

4.1.1.2 The "app:workspace" Element

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

4.1.1.3 The "app:collection" Element

(ed:the following assumes that PaceCollectionClasses will be accepted.  If PaceCollectionClasses is rejected, the references to the type, content and mediatype attributes need to be removed)

  atomContentList = comma separated list ("text", "xhtml", "html", media-range, uri, ncname)
  atomMediaTypeList = comma separated list (media-range)

  appCollection = 
    element app:collection {
      appCommonAttributes,
      attribute title { text },
      attribute href { uri },
      attribute prev { uri }?,
      attribute type { "entries" | "generic" },
      attribute content { atomContentList }?,
      attribute mediatype { atomMediaTypeList}?,
      (appMember* 
       & undefinedContent)
    }

 apply PaceCollectionClasses to the remainder of the app:collection discussion 

4.1.2 Metadata elements

4.1.2.1 The "app:member" Element

The 'app:member' element represents an single editable resource within a collection.

  appMember = 
    element app:member {
      appCommonAttributes,
      attribute title { text }?,
      attribute href { uri },
      attribute hrefreadonly { uri }?,
      attribute type { media-type }?,
      attribute updated { xsd:dateTime }
    }

4.1.2.1.1 The 'hrefreadonly' Attribute

This optional attribute identifies a URI which, on a GET request, responds equivalently to how the "href" URI would respond to the same request. Clients SHOULD NOT apply to this URI any HTTP methods that would be expected to modify the state of the resource (e.g. PUT, POST or DELETE). A PUT or POST request to this URI MAY NOT affect the underlying resource. If the "hrefreadonly" attribute is not given, its value defaults to the "href" value. If the "hrefreadonly" attribute is present, and its value is an empty string, then there is no URI that can be treated in the way such a value would be treated.

Clients SHOULD use the "href" value to manipulate the resource within the context of the APP itself. Clients SHOULD prefer the "hrefreadonly" value in any other context. For example, if the resource is an image, a client may replace the image data using a PUT on the "href" value, and may even display a preview of the image by fetching the "href" URI. But when creating a public, read-only reference to the same image resource, the client should use the "hrefreadonly" value. If the "hrefreadonly" value is an empty string, the client SHOULD NOT make public reference to the "href" value.

Impacts

Notes


CategoryProposals