Simple List Extensions Explained
Simple List Extensions Explained
Last updated: Mar 28, 2006
This document is a non-normative description (i.e. it is not an official specification) of how to use the Simple List Extensions. It will be updated regularly to address questions or issues with the specification.
The official specification for the Simple List Extensions is located here:
https://msdn.microsoft.com/xml/rss/sle
Overview
The Simple List Extensions (SLE) is a set of extensions designed to do two things:
(1) Make it possible for publishers to declare in their feeds that the feed really represents a "list" (more on that later).
(2) Allow publishers to mark up their lists (and feeds) to note which sub-elements of the item (or entry) represent properties that the user may be interested in sorting or grouping on.
SLE 1.0 accomplishes this with two extensions, one which identifies the feed, and the other which allows for feeds to be self-describing.
Examples
Simple RSS 2.0 example
<rss version="2.0"
xmlns:cf="https://www.microsoft.com/schemas/rss/core/2005"
xmlns:book="https://www.example.com/book">
<channel>
<cf:treatAs>list</cf:treatAs>
<title>Books in My Collection</title>
<link>https://www.example.com/collectionofbooks.htm</link>
<cf:listinfo>
<cf:sort label="Relevance" default="true" />
<cf:sort ns="https://www.example.com/book"
element="firstedition" label="First Edition" data-type="date" />
<cf:group ns="https://www.example.com/book" element="genre" label="Genre" />
</cf:listinfo>
<item>
<title>Great Journeys of the Past</title>
<author>Bob</author>
<description>A wonderful history of great journeys</description>
<book:firstedition>Sat, 07 Sep 2002 00:00:01 GMT</book:firstedition>
<book:genre>Travel</book:genre>
</item>
<item>
<title>Horror Stories, vol 16</title>
<author>Steve</author>
<description>Our favorite horror author provides us with another great collection</description>
<book:firstedition>Thu, 25 Aug 2005 00:00:01 GMT</book:firstedition>
<book:genre>Horror</book:genre>
</item>
</channel>
</rss>
Online version here.
This example shows a feed containing two books. The listinfo element, indicates to the client that it should do two things:
(1) Provide two sorting controls:
The first, to be labeled "Relevance" just displays the sort order in the order it came in the list.
The second, to be labeled "First Edition", allows sorting by the date in each item.
(2) Provide a grouping or filtering control, labelled "Genre" that allows grouping by the Genre. The client has (at least) two options:
The client could provide a grouping control, that rearranges the list to show each item grouped by its genre (all the Travel items together, and all the Horror items together); or
The client could provide a list of all of the unique values in the genre (travel and horror) and allow the user to filter the list to only the items in a particular genre.
Live Examples
These are live examples of SLE-enhanced feeds:
Amazon.com Wish List: Subscribe
Yahoo! Music Top Songs: Subscribe
eBay Store feed: Subscribe
Here are a couple other interesting examples of feeds:
PDC 2005 Session List
https://commnet.microsoftpdc.com/rss/pdcsessionsrss.aspxSample Security Bulletin Feed [this feed is not live -- don't subscribe to it] :
https://sean.members.winisp.net/rsssec/secrss.xml
Identifying a List
A common question is: what is a list? Well, when we use list in this document and in the specification, we mean a specific thing. To use the words of the official spec: A list is an ordered collection of items with similar properties.
There are several examples of lists that we commonly use: music playlists, photo albums, top 10 songs, wish lists, even search results.
To provide contrast, feeds :
1. Feeds are typically time-ordered, though in most cases, feeds are explicitly defined such that items do not have a specific order with in the feed itself).
2. Feeds typically represent a subset (usually the most recently modified items) of the all of the content available.
Lists are:
1. Ordered (not necessarily by time), and the order within the feed should be respected by the client.
2. The List represents a complete copy of content available.
What does this mean?
Simply put, if the publisher indicates that the feed is a list, the client needs to modify its behavior in certain ways.
For a normal (non-list) feed, a client typically behaves like this (assuming it is a client that creates a local cache of the items when subscribed to a feed):
(1) Download a copy of the feed.
(2) Compare the items in the feed with the items it has cached locally.
- If an item is new, it is added (or prepended) local set of items. It is marked as "new"
- If it already has a local copy of a downloaded item, it compares the downloaded and local versions of the items.
- If the downloaded item is a modified version of the existing one, it replaces it and marks it as new.
- If the downloaded item is the same as the existing one, then nothing happens
At the end of this process, the client has effectively merged the downloaded feed and the local feed, and marked the new or modified items as "new."
For a feed marked as a list, the client needs to add two additional behaviours after doing everything above:
(3) Compare the local items with those in the downloaded list.
- If an item was stored locally and it is no longer in the list downloaded from the server, it should be removed from the local copy.
- If items have changed order within the downloaded list, the client should reorder the local copy to match the downloaded list.
At the end of this process, the client has effectively created a local version that exactly matches the list downloaded from the server, and has marked the new or modified items as "new."
How do I mark a feed as a list
Simply put, you add this XML element to your feed:
<cf:treatAs>list</cf:treatAs>
Here is an example:
RSS 2.0 <rss version="2.0" xmlns:cf="https://www.microsoft.com/schemas/rss/core/2005">
<channel>
<cf:treatAs>list</cf:treatAs>
...
<item>
...
</item>
</channel>
</rss>
We'll add some examples in other feed formats soon.
Lightweight feed description
The other major part of SLE 1.0 is the ability to specify which properties of the items in the list (or feed) are useful or interesting to sort or group. These are intended to be hints to the client (which it is free to ignore), to provide a richer user experience to the clients users.
Here's the structure of the "listinfo" element, which is how this should be described.
<cf:listinfo>
<cf:sort
ns="<cf:group
ns=" namespace "
element=" element "
label=" User-readable name for the grouping " /><cf:listinfo>
There are several examples of this extension in action in the "Examples" section above.
Only certain types of properties can be supported by the Simple List Extensions 1.0. Specifically:
- The value which is to be sorted or grouped must be the value of the property (the character data contained in the element). Values of attributes cannot be accessed (the property element may include attributes, however. They are simply ignored from the perspective of the Simple List Extensions).
- The property referred to must have no child-elements.
- In general, only one instance of a property should appear in each item. Clients are free to ignore repeated instances of properties or may provide support.
In the context of Atom 1.0, "Simple Extension elements" are supported, while "Structured Extension elements" are not.
To be clear, lists (whether expressed in RSS or Atom) may still contain properties that do not fit these rules, but their values cannot be used for sorting or grouping.
The Future of Simple List Extensions
SLE 1.0 is designed to be the simplest possible way to expose useful functionality for lists. There are a number of scenarios it does not accomplish (for example, you cannot create a list that sorts on the values of attributes of child-elements). Future versions of the SLE specification may address these and other areas. Please send feedback or comments!