Abstract
Provide a way to allow existing members within an Entry Collection to be efficiently tagged with <atom:category> metadata. Further, the mechanism should guarantee that category data is the only part of the entry that can be changed.
Author: Kyle Marvin / Mark Lucovsky / Arthur Zwiegincew
Status
Draft
Rationale
A common usage of categories is "tagging" content with additional metadata based upon either content provider or user-defined ontologies. In some social collaboration systems, the application of categories to content may be done dynamically (either by users or by automated systems) who are not the original authors of the content.
In draft-ietf-atompub-protocol-04, the only available mechanism for applying new category metadata to an Atom member in a Entry Collection is to perform a PUT operation to update the entire entry.
This raises two basic issues:
-
Adding a relatively small amount of metadata (one or more category tags) requires rewriting a much larger amount of data (the entire atom:entry element).
-
There is no easy mechanism to enforce that addition of category entries (and only the addition of those entries) is the only operation available to a user or class of users. A user must be able to update any and all elements of the atom entry simply to add category metadata.
Having an operation that makes the adding of new category elements to an existing entry in the Entry Collection would resolve both of these issues.
Proposal
Make the following changes to the draft-ietf-atompub-protocol-04 spec:
Add a new section just before section 6.1 (Editting Entry Resources):
6.x Category Document
A Category document represents a collection of 'atom:category' elements that are to be applied to an Atom entry.
6.x.1 Categories Element
The categories element acts as a collection for one or more atom:category elements.
appCategories = element app:categories { (atom:category)* }
The 'app:categories' element MAY CONTAIN one or more 'atom:category' elements.
Section 6.1
Modify the table labeled "Processing Client Requests" to add a new row beneath the "Atom Body" row with contents of:
Category Body X X X Categorize
And add another row below the one labeled "Soap-Body with Web-Method DELETE" with contents of:
Soap-Body withe Web-Method POST X X X Categorize
Add the following new section after the Section 6.2 (Role of Atom Entry...):
Section 6.3: Categorizing Entries
The Categorize edit operation defined in section 6.1 will add each of the 'atom:category' elements contained with the Category document contained within the request to the target Entry resource. If the resource already contains a matching category element, then no change will occur for that element and the operation will still be considered successful.
Examples
GET /myFeed/myEntry 200 OK <?xml version='1.0'?> <entry xmlns='http://purl.org/atom/ns#draft-ietf-atompub-format-09'> <id>45678132</id> <updated>2005-05-23T15:38:00-08:00</updated> <title>Fubar</title> <content type='text'>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</content> <link rel='alternate' type='text/html' href='http://myserver.com/myFeed/myEntr y.html'/> <category term='foo'/> </entry> ---- POST /myFeed/myEntry <?xml version='1.0'?> <app:categories xmlns='http://purl.org/atom/ns#draft-ietf-atompub-format-09' xmlns:app='http://purl.org/atom/ns#draft-ietf-atompub-protocol-xx'> <atom:category term='bar' scheme='fubar.com'/> </app:categories> 200 OK ---- GET /myFeed/myEntry 200 OK <?xml version='1.0'?> <entry xmlns='http://purl.org/atom/ns#draft-ietf-atompub-format-09'> <id>45678132</id> <updated>2005-05-23T15:39:00-08:00</updated> <title>Fubar</title> <content type='text'>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</content> <link rel='alternate' type='text/html' href='http://myserver.com/myFeed/myEntr y.html'/> <category term='foo'/> <category term='bar' scheme='fubar.com'/> </entry>
Impacts
-
Adds new POST method usage and one additional Soap Web-Method for Entry Collection members.