The Movable Type and Professional Network Wiki has been moved to wiki.movabletype.org.

AtomInteropProfile

[Login] Change #14 by Byrne Reese at 2006-01-08 19:49:40.

The following content has unclosed HTML tags: LINK (3 open)

Six Apart Atom Interoperability Profile

Below is a proposal for a Six Apart AtomInterop Profile. This document serves the purpose of defining and documenting the common set of Atom features supported by all Six Apart products. Where specifications are unclear, or in-flux, this also documents our shared interpretation of the given requirement so that it is clear how each product implements a feature, and in turn what customers and developer should expect from Six Apart Atom endpoint.

Status

This document is in DRAFT and is not yet complete.

Atom Syndication Format

The Atom Syndication Format is a specification that defines the formats for Atom feeds, and entries. It serves as a normative reference for the Atom Publishing Protocol.

feed/link[@rel=self]

This element MUST provide a link to the current feed. It should contain the URL identical to what the user requested.

Ironically, the intent of this feed is to refer to the Atom Feed one should subscribe to, if for example, you are looking at page 5 of a 10 page feed.

feed/link[@rel=alternate]

Pointing to the HTML Version

This element MUST reference the HTML version of this feed. The @type link should be text/html.

Pointing to the Mobile Version

PROVISIONAL - Tatsuhiko has put together a proposal for linking to alternative versions of a feed, specifically to a version optimized for mobile devices. His proposal is derived from the HTML 4 specification which specifies the use of a link@media attribute. For example:

<link rel="alternate" href="..." x:media="mobile" />

This element is optional. If present then link@type MUST be application/xhtml+xml, and link@x:media MUST be 'handheld.'

feed/link[@rel=service.post]

This element MUST reference to the endpoint to which new entries will be posted.

feed/link[@rel=subscribe]

This element MUST reference the URL of the feed that one should subscribe to. This is especially relevant if I am paging through a feed, so that when I am on the 5th page, I subscribe to the "top" or page 1.

Note: this element may be renamed to "current"

feed/link[@rel=next]

This element SHOULD be present for any feed that is a partial representation of the feed's complete data set. For example, a feed of a yearly archive may have 300 entries in it, but only 10 entries per page. This element therefore would be used to move forward (e.g. the next 10 entries) in the result/dataset.

The element MUST NOT be present if the user has reached the end of the current resultset/dataset/feed.

feed/link[@rel=previous]

This element SHOULD be present for any feed that is a partial representation of the feed's complete data set. For example, a feed of a yearly archive may have 300 entries in it, but only 10 entries per page. This element therefore would be used to move backwards (e.g. the previous 10 entries) in the result/dataset.

This element MUST NOT be present if the user is at the beginning of the current resultset/dataset/feed.

Note: the next and previous link relations do not have anything to do with the order of a feed. For example, as to whether the "next" feed moves forwards or backwards in time is complete feed-dependent.

feed/link[@rel=first]

This element SHOULD be present if there are also @rel=next or @rel=prev link relations present.

This element MUST point to the feed at the beginning of the current resultset/dataset/feed.

This element is present to faciliate a person wishing to jump to the beginning and then paginate forward through the feed.

feed/link[@rel=last]

This element SHOULD be present if there are also @rel=next or @rel=prev link relations present.

This element MUST point to the feed at the end of the current resultset/dataset/feed. For example, if a feed has a total of 59 entries, and each page contain 10 entries, then @rel=last SHOULD reference a feed containing entries #49-#59.

This element is present to faciliate a person wishing to jump to the end and then paginate backwards through the feed.

feed/id

"Conveys a permanent, universally unique identifier for an entry or feed" in accordance with the Atom Feed specification.

feed/title

The value of this element MUST be user's specified title for their weblog or journal.

This element MUST contain a value. If the user has not specified a value to use, then the application MUST provide one.

feed/subtitle

This element is optional. If present, it should contain the user provided description of the blog or journal.

feed/updated

The intended use of this field is to provide a reliable mechanism for clients and aggregators to determine the freshness of the feed in question.

The element refects the date and time of the last time any aspect of the feed was modified, including but not limited to entries, feed title and other meta data, etc.

This element SHOULD NOT be editable by users. It SHOULD reflect a datetime determined and controled by the system.

feed/category

This element is used to indicate to a client that the current feed/document is restricted to a specific category or tag, should we offer category and tag feeds.

feed/!category@term

The fully qualified name for a category, or the normalized version of a tag.

feed/!category@label

The display name for a category or tag.

feed/!category@scheme

Used to differentiate between categories and tags.

feed/generator

The name of the product generating the feed.

feed/!generator@uri

A url to the products homepage.

feed/entry

The "entry" element is used not only to encapsulate post data, but comments, and TrackBacks as well (and possibly even categories, see Open Issues below).

feed/entry/id

"Conveys a permanent, universally unique identifier for an entry or feed" in accordance with the Atom Feed specification.

feed/entry/in-reply-to

For use with comments and TrackBacks only. See "Extensions" below.

feed/entry/title

The title of the post or journal entry.

For comments this would refer to the "Subject" of the comment (for LiveJournal).

For TrackBacks this would refer to the title of the originating post/ping.

feed/entry/published

The date of original publication.

While there may be a correlation between the created date and published date of an entry, a relationship is not implied or necessarily intended.

The user MUST NOT be allowed to modify the contents of this element.

Note: to facilitate post scheduling, please use James Snell's Blog Control Atom Extension.

feed/entry/updated

The intended use of this field is to provide a reliable mechanism for clients and aggregators to determine the freshness of the entry in question.

The element refects the date and time of the last time any aspect of the entry was modified, including but not limited to the title, the content, etc.

This element SHOULD NOT be editable by users. It SHOULD reflect a datetime determined and controlled by the system.

feed/entry/summary

The /feed/entry/summary element is intended to contain a concise and complete abstract of the entry. All our products support the ability for a user to specify a preferred summary to use. In the event that a user has provided their tool or service with a summary, or excerpt to use, then the tool or service MUST use that value for the "summary" element.

If the user has not specified a specific summary or excerpt to use, then the "summary" element MUST be omitted, unless the user has elected not to display the contents of their posts within their feed.

If the user has elected not to display the contents of their posts within their feed, then the "summary" element MUST be present. If the user has not specified a summary or excerpt to use, then the tool or service MUST provide one of its own.

feed/entry/content

If the user has elected not to display the contents of their posts within their feed, then:

the "content" element MUST be empty
the "content src=''" attribute must point to the full text of the post

Considerations for LiveJournal

Provided that the user has elected to include the contents of their posts within their feed, then the contents of the Entry field MUST be encoded within the "content" element.

If a user failed to include or chose to omit text in their entry, then the "content" element MUST be present, but MUST be empty or nil.

Considerations for MovableType and TypePad

Both MovableType and TypePad support the notion of an Entry Body, Extended Entry and an Excerpt. In regards to how these discreet pieces of content should be represented within a feed, or via the Atom protocol, the following should apply:

The "content" element MUST contain the contents of the Entry Body field.
The Extended Entry should be contained within a proprietary Six Apart Atom extension, within the "content-extended" element.
The Excerpt field is intended to be used within the "summary" element (see above requirements).

feed/entry/author

If all the entries within a feed are written by the same author then the feed MUST include an /feed/author element, and SHOULD NOT include a /feed/entry/author element for each entry.

If at least two entries within a feed is written by different authors, then each /feed/entry MUST contain an "author" element, and there SHOULD NOT be a /feed/author element.

feed/entry/author/name

This element MUST be present.

feed/entry/author/uri

This element is optional.

feed/entry/author/email

This element is optional.

feed/entry/category

If a tag or category has been associated with the entry, then one or more category elements MUST be present.

feed/entry/!category@term

This element MUST refer to canonicalized version of the category in question. For example, if the term is a category within a heirarchy, then the term SHOULD represent the entire heirarchy, e.g. "/Technology/Programming/Open_Source".

If the category is a tag, then term SHOULD represent the canonical form. For example, if a user provided the tag "New York" then the canonicalized form may be "newyork" (no capitals, no spaces, etc).

feed/entry/!category@label

This element MUST refer to the preferred text to use when displaying the term to the outside world. For example, a category term may be "/Technology/Programming/Open_Source", but the label should be "Open Source".

feed/entry/!category@scheme

This element MUST allow clients to differentiate between tags, categories and any other classification scheme we derive.

If the category element refers to a category (like it may in TypePad or Movable Type), then @scheme MUST be equal to "sixapart:category".

If the category element refers to a tag (like it may in Comet, LiveJournal, or Movable Type), then @scheme MUST be equal to "sixapart:tag".

feed/entry/link[@rel=service.edit]

The URL to which updates this entry will be posted.

feed/entry/link[@rel=service.post]

The URL to which new comments are posted to an entry.

If an entry has commenting enabled for an entry, then a "link rel='service.post'" element MUST be included.

If an entry has commenting disabled for an entry, then a "link rel='service.post'" element MUST NOT be included.

feed/entry/link[@rel=alternate]

The URL to a text/html version of this entry.

feed/entry/link[@rel=enclosure]

The URL to a related media object (a.k.a. "podcast").

feed/entry/link[@rel=service.ping]

The URL to which TrackBacks should be sent.

Note: This is provisional, and non-standard.

Extensions

The following section is devoted to how Six Apart is utilizing Atom Extensions to fulfill the stated requirements of the AtomInterop project.

Feed Thread Extension

The Feed Thread Extension will be used in order to communicate to endpoints the comments and TrackBacks related to an entry.

Feed Thread Spec, (draft 2), Author: James Snell

Requirements

A comment and TrackBack MUST be designated as an "entry", with an "in-reply-to" element.

A comment MUST specify the "subject" for a comment within the "title" element. The "title" element can be omitted should the application not suppport the ability to specify a subject for a comment or TrackBack.

A comment MUST specify the contents of a comment within the "contents" element.

A TrackBack MUST contain an "alternate" link relation associated with the "entry" element that MUST refer to the origination of the TrackBack ping.

A TrackBack MUST specify a the contents of the TrackBack within the entry/summary element.

A TrackBack MUST specify a valid URL for the source of the TrackBack within the element/content@src attribute.

entry/in-repty-to

The presence of the "in-reply-to" element for an entry implies that the entry is a comment or TrackBack. The "in-reply-to" element MUST be de-referencable and MUST point to the entry/comment to which the entry is in response to.

entry/in-repty-to@title

If the entry is a comment or TrackBack, then the title attribute MUST contain the title of the entry to which the current entry is in response to.

entry/link@[rel=replies]

If an entry has comments associated with an entry, then the entry MUST contain a "link rel='replies'" element.

If the application supports threaded comments, then it is perfectly acceptable for a comment "entry" to also contain a "link rel='replies'" element.

Note: some have implemented this is as a link relation called "comments."

Threaded Comments

It is up to the discretion of the Atom implementation as to whether a comment feed contains a list of comments sorted by either the published date of the comment, or sorted by Thread.

Example

<entry>
  <summary>Re: I love Atom, wheeee!</summary>
  <id>http://some.domaim.com/2005/06/12/foo.html#comment-1243</id>
  <in-reply-to title="I love Atom, wheeee!">
    http://some.domaim.com/2005/06/12/foo.html
  </in-reply-to>
  <author><name>Byrne Reese</name></author>
  <contents>
    This is what I have to say about Atom.
  </contents>
</entry>

Feed History

The Feed History Extension will be used in order to allow clients to navigate an entire archive of entries.

Feed History Spec, draft 4, Author: Mark Nottingham

The Feed History Extension specifies the following elements:

"prev" element - a dereferencable element that points to the previous feed in the archive
"incremental" element - indicates that the document is not a complete representation of the entire feed, and that one should navigate through the feed using the "prev" element.
"archive" element - defaults to "false". If true, indicates that the feed is an archive and should not change over time, and that the feed is not intended to be subscribed to.

Open Issues

how to represent comment and trackback counts
hot to represent the total number of entries in a feed (for pagination, e.g. "now showing x to y of z")
- Perhaps we can use the OpenSearch method using the !totalResults, startIndex and itemsPerPage elements.
how to retrieve a list of all feeds (there could be a feed for each category, each tag, each archive, etc)
how do you, or can you specify your own ID when posting?
feed/id and the rules for uniqueness
log bug: MT and TP do not reliably track the created on, last modified dates
default sort orders for feeds?
is it URL or URI for authors?
if an entry has never been modified, there is no "updated" element
"summary" element - LJ does not support the ability for a user to provide their own summary
omit content element under some circumstances? when a user specifies not to publish the whole content of their post?
supporting vcard microformat for authors?
Atom cannot officially reference TrackBack until TrackBack becomes a standard. We need to write up an IETF proposal and submit it to the organization.
"link rel='service.categories'" is a non-standard implementation. I recommend modifying this to be more standards compliant. The following was suggested by the Atom Working Group, to publish a feed of categories of the format (where each category is an entry with a pointer to a feed, etc):

Category 1 uri ...

References