Abstract
-
Merge and streamline the definitions of the Atom Collection and Introspection documents in a way that is consistent with the Atom Syndication Format definitions.
-
optional type attribute added to app:member to indicate the media type of the resource
-
title attribute on the app:member made optional. (title makes sense for entry collections, does not make as much sense for generic collections as it is unclear how the title would actually ever be set)
-
extensionElement content for elements is replaced with undefinedContent. (without a defined extensibility mechanism for APP, it does no good to talk about extension elements)
Eliminate the two different app:collection elements that are currently defined in the protocol spec
Prereqs the acceptance of the PaceAppDocuments and PaceCollectionClasses proposals
Also makes a few modifications to various elements:
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
-
The "app:service" element is the document (i.e., top-level) element of an Atom Publishing Protocol Introspection Document, acting as a container for workspaces. It's element children consist of zero or more app:workspace elements.
appService = element app:service { appCommonAttributes, (appWorkspace* & undefinedContent) }
-
app:service elements MAY contain any number of app:workspace elements.
4.1.1.2 The "app:workspace" Element
-
The "app:workspace" element contains information elements about the collections of resources available for editing. It's element children consist of zero or more app:collection elements.
appWorkspace = element app:workspace { appCommonAttributes, attribute title { text }, (appCollection* & undefinedContent) }
-
app:workspace elements MUST contain a title attribute which conveys a human-readable name for the workspace. The title attribute is Language Sensitive.
-
app:workspace elements MAY contain any number of app:collection elements.
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)
-
The "app:collection" element describes collections of editable resources. This element can appear as a child of the app:workspace element, or it can appear as the document (i.e., top-level) element of a standalone Atom Publishing Protocol Collection Document.
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) }
-
app:collection elements MUST contain a title attribute whose value conveys a human-readable name for the collection. The title attribute is Language Sensitive.
-
app:collection elements MUST contain a href attribute whose value conveys the URI of the collection.
-
app:collection elements MAY contain a prev attribute whose value identifies a collection document containing member elements updated earlier in time.
-
app:collection elements MUST contain a type attribute whose value is either "entries" or "generic".
-
app:collection elements whose type attribute value equals "entries" MAY contain a content attribute whose value is a comma separated list of values including: "text", "xhtml", "html", a media-range, a URI, or NCName.
-
app:collection elements whose type attribute value equals "entries" MUST NOT contain a mediatype attribute.
-
app:collection elements whose type attribute value equals "generic" MUST contain a mediatype attribute whose value is a comma separate list of media-range values (e.g., audio/*, */*, application/*+xml, etc).
-
app:collection elements whose type attribute value equals "generic" MUST NOT contain a content attribute.
-
app:collection elements that appear as children of app:workspace elements MUST NOT contain any app:member elements.
-
app:collection elements that appear as the document (i.e., top-level) element of a standalone Atom Publishing Protocol Collection Document MAY contain any number of app:member elements.
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 } }
-
app:member elements MAY contain a title attribute whose value conveys a human-readable name for the member. The title attribute is Language Sensitive.
-
app:member elements MUST contain a href attribute whose value conveys the URI used to edit the member resource.
-
app:member elements MAY contain a hrefreadonly attribute.
-
app:member elements MAY contain a type attribute whose value conveys the media type of the member resource.
-
app:member elements MUST contain an updated attribute whose value conveys the most recent instance in time when the member was modified in a way that the publisher considers significant.
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.