Developers Wiki - attentionxml

Attention.XML

Draft Specification 2004-12-28

Copyright

For the moment this specification is (C)2004-2005 by the author(s) and Technorati. However, Technorati intends to submit this specification to a standards body with a liberal copyright/licensing policy such as the

GMPG. See the

GMPG Principles for more details. Anyone wishing to contribute to this effort MUST read those principles, especially those regarding copyright and licensing, and agree to them before contributing.

[MicroFormatCopyrightStatement]

Patents

Technorati neither holds nor intends to apply for any patents on anything required to implement this specification.

[MicroFormatPatentStatement]

Acknowledgments

Thanks to:

All the attendees at the FOO Camp 2004 Attention.XML presentation for their excellent questions and feedback.
Scott Johnson for pushing for simplicity, vendor neutral property/attribute names, and a minimal sync profile.
Jeremy Zawodny for suggesting the ability to tag and annotate the URLs of blogs/sites and posts/pages.
Timothy Appnel for constructive feedback and suggesting the simple and short property name "tags" for the abovementioned feature.

Introduction

Attention.XML is an open standard, built on open source (see XOXOSampleCode) that helps you keep track of what you've read, what you're spending time on, and what you should be paying attention to.

[attentionXmlIntroduction]

Problem Statement

How many sources of information must you keep up with?
Tired of clicking the same link from a dozen different blogs?
RSS readers collect updates, but with so many unread items, how do you know which to read first?

Attention.XML is designed to to solve these problems and enable a whole new class of blog and feed related applications.

[attentionXmlProblemStatement]

Format

Format Summary

Attention.XML is an XML file (specifically an XOXO file) that contains an outline of feeds/blogs, where each feed itself is an outline, and each post is also an outline under the feed. This hierarchical outline structure is then annotated with per-feed and per-post information which captures such information as, the last time the feed/post was accessed, the duration of time spent on the feed/post, recent times of feed/post access, user set (dis)approval of posts, etc.

Format Schema

The Attention.XML outline contains the following types of list items. Property values are text strings unless otherwise stated.

Group. Groups do NOT have a URL field. However, each group does have the following:

title. Essentially this is the user given name for a group of blogs in a blogroll or feeds in a feedroll.
children: groups or blogs

Blog/Feed/Site. Each blog/feed/site has the following:

title. Name or title.
url. Every item has a notion of a primary URL, and this is it.
alturls. list of secondary URL/title pairs for the resource, e.g. for blog or other feed types etc. type info can be retrieved via HTTP request header and cached as necessary.
etag. HTTP 1.1, sec. 14.19
lastupdated. to be filled in by attention.xml storage/sync server.
dateadded. ISO8601 datetime when added to blogroll, added by clients. clients may ignore retrieved value.
dateremoved. ISO8601 datetime when removed from blogroll, added by clients, processed by storage/sync servers POST command.
lastread. ISO8601 datetime indicating the last time the user has explicitly read (perhaps by selecting) a feed.
readtimes. FIFO queue (length up to implementation, recommended min 16) of ISO8601 datetime + secondsread space-delimited pairs.
userfeedtitle. user given name to a feed, to be filled in by clients, AKA givenname.
rel/xfn. social relationship to the author represented by this blog/feed. See XFN for details.
rev/votelink. vote-for | vote-against | vote-abstain | "" / blank. See VoteLinks for details.
tags. A general mechanism for user tagging/annotating. See Technorati Tags for examples of tags.
children: posts/items

Post/Item/Page. Each post/item/page has the following:

title. Name or title.
permalink/guid. acts as unique identifier and is assumed to be canonical, i.e. as described in http://www.xml.com/lpt/a/2004/08/18/pilgrim.html .
type. indicates the MIME Content-Type of the post permalink. default is text/html.
etag. HTTP 1.1, sec. 14.19
lastupdated. ISO8601 datetime indicating last time the post was updated.
lastread. ISO8601 datetime indicating the last time the user has explicitly read (perhaps by selecting) a post/item.
duration. non-negative int represents seconds the user spent reading this post/item.
followedlinks. list of URLs from the post that the user has clicked or accessed.
rev/votelink. vote-for | vote-against | vote-abstain | "" / blank. See VoteLinks for details.
tags. A general mechanism for user tagging/annotating of this item.
children: none

Example

per-feed

The following OPML legacy fragment, after the head information, for per-feed information, as it already exists:

<outline text="atitle" 
         description="descstr"
         url="aurl"
         atomurl="anatomurl"
         xmlurl="anrssurl"
         type="typestr" ...>

would look like this in typical Attention.XML XOXO fragment:

<li><a href="aurl" type="typestr">atitle</a> 
    <dl><dt>description</dt><dd>descstr</dd>
        <dt>alturls</dt>
        <dd><ul><li><a href="anatomurl">atomurl</a></li>
                <li><a href="anrssurl">xmlurl</a></li></ul></dd>
    </dl>
</li>

Attention.XML extends this with the properties noted in the schema above:

alturls, etag, lastupdated, dateadded, dateremoved, lastread, readtimes, userfeedtitle, rel, tags

per-post

In OPML legacy, each feed has a set of sub-elements, represented by a set of outlines.

<outline type="item" 
         permalink="permalink or guid"
         guid="permalink or guid"
         lastread="ISO-8601 date"
         duration="seconds value"
         followedlinks="http://example.com/1 http://example.com/2"
         rev="votelink">

which would look like this in typical Attention.XML XOXO:

<li><a href="permalink or guid" rev="votelink">title</a> 
        <dl><dt>lastread</dt><dd>ISO-8601 date</dd>
            <dt>duration</dt><dd>seconds value</dd>
            <dt>followedlinks</dt>
            <dd><ul><li><a href="http://example.com/1">link1</a></li>
                    <li><a href="http://example.com/2">link2</a></li></ul></dd>
        </dl>
</li>

The permalink or guid value is required - you have to have one or the other. These serve as an identifier for the post item.
The lastread is the same as above, an ISO-8601 date that shows when the item was accessed.
The duration is the same as well - number of seconds spent on this item.
etc. all as defined above in the schema.

So that's the format. AttentionSample outputs are also available.

Proof of Concept

To see what Technorati might do with an Attention.XML file or OPML subscription list export (like NetNewsWire's), use the following URL:

http://www.technorati.com/attention.html

BTW, when we're out of prototype stage, the URL for the webservice will probably change from http://www.technorati.com/attention.html to something else, but that should be a minor change to make.

See also Technorati's AttentionQuery documentation of Technorati's Attention.XML web service API.

Profiles

There are many different types and classes of Attention.XML applications. Defining a set of profiles appropriate for each helps ensure a high level of interoperability even among varied tools.

Minimal Feed Sync Profile

A minimal feed syncing application or service must support the following subset of the Attention.XML schema:

Group. Groups do NOT have a URL field. However, each group does have a "title". Groups must be parsed only as much as necessary to derive an overall list of feeds.

title. Clients must look for the existence of the "title", but may ignore its contents.
children: groups or blogs

Blog/Feed. Each blog/feed has the following:

URL. Every item has a notion of a primary URL, and this is it. We'll get to alternates later.
lastread. ISO8601 datetime indicating the last time the user has explicitly read (perhaps by selecting) a feed. Clients must set this appropriately. Leave blank or do not specify to indicate that the user has never read this feed.
children: posts/items

Post/Item. Each post/item in a feed has the following:

permalink/guid.
lastread. ISO8601 datetime indicating the last time the user has explicitly read (perhaps by selecting) a post/item. Clients must set this appropriately. Leave blank or do not specify to indicate that the user has never read this post.

When activated/launched, the application must access the user's Attention.XML file from storage (e.g. local storage or be a web-based synching service) and load it into memory.

When the user clicks or otherwise selects a feed, the application must update the "lastread" property for that feed in the in-memory store.

When the user clicks or otherwise selects an item from a feed, the application must update the "lastread" property for that item in the in-memory store.

All other either unrecognized or unsupported properties present in the Attention.XML that is retrieved from storage must simply be maintained and roundtripped when stored.

When deactivated/quit, the application MUST write the local in-memory Attention.XML to storage (e.g. local storage or a web-based synching service), by doing the following: re-read the Attention.XML (in case it has been changed since last read by another client) from storage, merge in local changes made in the client, and finally write out the resultant updated Attention.XML. The application SHOULD sync the Attention.XML at other opportune times (perhaps every so often, or when the user has idled a certain amount), in order to both share local client changes with any other clients, and to reflect any updated "lastread" states from other clients.

Feed Reader Profile

In addition to supporting the minimum sync profile as detailed above, typical blog/feed reading software should support the complete Attention.XML schema as follows.

When the user adds a feed to their list, set its "dateadded" property accordingly.
When the user removes a feed from their list, rather than deleting it, simply hide it in the userinterface and set its "dateremoved" property accordingly.
When updating the "lastread" property on a feed/blog, first push the current value of "lastread" into the "readtimes" property, with any available length of time reading available.
When it is possible to detect the time spent by a user reading a post/item, store that time value in seconds in the "durationread" property for that post/item.
When the user clicks on a hyperlink in a post/item, add it to the set of "followedlinks" for that post/item.
When the user customizes the name of a feed/blog in the list, store the customized name in the "userfeedtitle" property.
Provide the user with an interface to specify their social relationship to the person (if any) represented by a specific feed/blog in the list, and update the "rel" property accordingly with the proper XFN value(s).
Provide the user with an interface to approve/disapprove/abstain-opinion about both a feeds/blogs and posts/items, and when the user makes a selection, update the "rev" property accordingly with the proper VoteLinks value(s)
Provide the user with an interface to annotate both feeds/blogs and posts/items with one or more "tags" (essentially, keywords). See Technorati Tags for examples of Tags.

Attention Storage/Sync Service Profile

An Attention Storage/Sync Service MUST support the following verbs:

GET. Clients MUST be able to retrieve the Attention.XML file from the service. Optional extensions include the ability for clients to request the Attention.XML file for a particular user who has provided their username/password, and ability for users to share their Attention.XML with other users, in general, or perhaps limited to a subset of their social network. Additionally, several blog/feed/post/item properties may be set upon retrieval: "lastupdated", "etag", "alturls", "title". In addition, if the service retrieves and parses blogs/feeds itself, it SHOULD add to the "alturls" property accordingly from any auto-discovery URLs that are found in the retrieved blog/feed.
POST. Services MUST be able to accept an Attention.XML file from any client (same optional extensions), and merge it into any previous versions of the file as follows:

For all blogs/feeds/posts/items, keep track of their most recent "lastread" value respectively.
If a blog/feed has the "dateremoved" property, if its value is more recent than any "dateadded" property, then remove the blog/feed from the list, otherwise simply remove the "dateremoved" property.
For all blogs/feeds, sort both sets of "readtimes" together by recency and keep at least the recommended minimum of 16.
Merge "followedlinks" as a union for a post item.
Accept any feed item "durationread" property that is higher than the current value.
Accept any new/different feed "userfeedtitle", "rel", "rev", "tags" properties from the POST.
Accept any new/different feed item "rel", "rev", "tags" properties from the POST.

Sample Code

See the XOXOSampleCode page for open source sample code to read and write Attention.XML.

References

Normative References

Informative References

Implementations

Technorati AttentionQuery API of the TechnoratiApi
Niall Kennedy's NetNewsWire export

Significant changes From previous versions

2005-06-09

Updated references to VoteLinks to use "rev" instead of "rel", per respective fix to VoteLinks spec.

2004-12-28

Removed property groups from "blog/feed/site" for simplicity since there are no known implementations/aggregators that support a user model of allowing a feed to be in more than one group. Old property definition: groups. list of user defined groups that the user organized the feed into. yes it makes sense for a feed to be in more than one group. note: implementations may limit this to one group per feed, if so, use first group from list.
Added property tags to blog/feed/site and post/item/page.

2004-10-01

First thorough design, based on XOXO.

Discussion

Join the Technorati Developer program and our developers list where there is active discussion of Attention.XML.
AttentionXMLFAQ - check here first for questions and answers.
AttentionXMLDiscussion - have a larger issue that doesn't fit as a question? Add it here.
AttentionXMLBrainstorming - what authors and implementers are currently thinking about, potential changes to the spec, etc.
See blogs discussing this page.

Nov	DEC	Jan
	28
2004	2005	2007

> attentionxml