Abstract
Adds the ability to query a site for a list of acceptable categories.
Status
Open
Author: JoeGregorio
Rationale
Categories are part of the original charter for the atompub working group, and in addition they are showing up in the wild: http://sixapart.com/developers/atom/typepad/
Proposal
Add the following to the protocol specification:
3.4 CategoryURI
The CategoryURI allows the client application to retrieve a list of category name-value pairs from the server. These name-value pairs are presented to the user to choose from when creating or updating an entry. The value of the name-value pair is sent in a dc:subject element of the entry.
3.4.1 Locating
The CategoryURI is found in the Introspection file. If the server supports a specific type of categorization then it SHOULD present a category facet in it's Introspection file. The 'name' for the CategoryURI in the Introspection file is 'categories'.
<?xml version="1.0" encoding='utf-8'?> <introspection version="0.3" xmlns="http://purl.org/atom/ns#"> <site title="Main Site" > <service name="post" href="http://example.org/reilly/post" /> <service name="feed" href="http://example.org/reilly/feed" /> <service name="categories" href="http://example.org/reilly/cat" /> </site> . .
3.4.2 Request
The only method specified for this URI is GET.
3.4.3 Response
The response from a successful GET on a CategoryURI is a Categories document. An example of such a document is:
<?xml version="1.0" encoding="utf-8"?> <categories version="1.0" xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-02"> <subject value="http://example.net/myontology/#books">Books</subject> <subject value="http://example.net/myontology/#travel">Travel</subject> <subject value="http://example.net/myontology/#movies">Movies</subject> </categories>
Given the above example response, if a new entry was created with a movie review it can be categorized by adding the following element to the POSTed entry:
<entry> . <dc:subject>http://example.net/myontology/#movies</dc:subject> . </entry>
The mime-type of the returned content is 'application/atom+xml'.
Any number of children 'atom:subject' elements may be present.
3.4.3.1 The "atom:categories" element.
-
The "atom:categories" element is the document (i.e., top-level) element of an Categories Document, acting as a container for category information that entries may be associated with. Its only child elements MUST be one or more atom:subject elements.
The "atom:categories" element MUST have a single attribute 'version' whose content indicates the version of the Atom specification that the feed conforms to. The content of this attribute is unstructured text.
The version identifier for this specification is "1.0".
3.4.3.2 The 'atom:subject' element conveys information about a single category. The contents of the 'atom:subject' element is a human-readable description of the category.
-
The "atom:subject" element MUST have an attribute 'value' whose content indicates the value to be submitted in a dc:subject element of an entry. The content of this attribute is unstructured text. The formatting of the content is determined by the categorization schema chosen.
For example, here is a fragment of a categories document for a site that is using the ITPC NewsCodes[1] :
<categories version="1.0" xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-02"> . <subject value="01001000">archaeology</subject> <subject value="01002000">architecture</subject> <subject value="01005000">cinema</subject> . </categories>
Key Questions
-
What do we do for large categorization schemes? For example, if I recall correctly just the category names for DMOZ totals over 300MB.
-
Do we need to indicate somewhere which categorization schema this is from, either something private, or indicate it is from a well known source, such as IPTC, DMOZ, etc.
-
Does this work for all the 'well-known' categorization schemes?
-
Are multiple dc:subject elements allowed in an entry? How do we distinguish if only 1 or if more are allowed?
Impacts
Notes
CREDIT: This idea and interface is inspired by the TypePad implementation: http://sixapart.com/developers/atom/typepad/
Update: Added a version attribute to the response.
Update: Added more detail on element and attribute meanings.