Simple List Extensions Specification

Version: 1.0a
Contact: Sean Lyndersay, Microsoft Corporation
Updated: March 14, 2006

Overview
  Background
Example
Simple List Extensions
  Namespace
  Identifying a List
  Lightweight Property Description
    Overview
    Sorting
    Grouping
Additional Information
Revision History
License Information

1.   Overview

The Simple List Extensions are designed as extensions to existing feed formats, such as RSS 2.0 and Atom, to make exposing ordered lists of items easier and more accessible to users.

The term “list,” as used in this document describes an ordered collection of items with similar properties. For example, a photo album may be described as a “list of photos.”

Note: This specification is designed to be as simple as possible. Additional information, explanation and examples can be found here. 

1.1 Background

A feed is a collection of items. The feed typically represents either a subset of or the entire collection of items that exist on a server.

Consumers of feeds need to process feeds differently based on the kind of feed content. For example, a feed that contains the entire collection of items on the server should be processed differently from a feed that contains only the most recently added or updated items. Additionally, certain information in the feed may be more relevant or useful for the consuming client to expose to the user than others.

The purpose of the Simple List Extensions is to define a set of XML elements that can be used in a feed to more completely describe the intent of the publisher to the client, so that that client can provide a more accurate, and useful representation of the feed to the user.

This specification includes two extensions, which can be used independently from each other: the first allows the publisher to indicate that the feed is a "list", which implies that the client should treat the feed differently from the way it treats normal feeds. The other extension can be used on any kind of feed (both feeds and lists) and allows the publisher to indicate to the client how it should treat certain item metadata.

2.    Example

This is an example of how the Simple List Extension elements would be used to define a list of book items (using the cf:treatAs element), with the following additional features:

1.   The publisher specifies that the default sort provided in the feed can be labeled “Relevance” when shown to the user (using the cf:sort element).
2.   The publisher specifies that the user should be allowed to sort by the date of publication of the first edition of the book (and that it can use the label "First Edition" to the user).
3.   The publisher specifies that the user should be allowed to group or filter by the different genres of books that occur in the list (using the cf:group element).

<rss version="2.0"
      xmlns:cf="http://www.microsoft.com/schemas/rss/core/2005"
      xmlns:book="http://www.example.com/book">
  <channel>
    <cf:treatAs>list</cf:treatAs>
    <title>Books in My Collection</title>
    <link>http://www.example.com/collectionofbooks.htm</link>
    <cf:listinfo>
      <cf:sort label="Relevance" default="true" />
      <cf:sort ns="http://www.example.com/book"
        element="firstedition" label="First Edition" data-type="date" />
      <cf:group ns="http://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>

3.    Simple List Extensions

3.1 Namespace

The following namespace declaration is used for XML elements in this document.

Namespace   http://www.microsoft.com/schemas/rss/core/2005

Description     This namespace defines all of the elements in this specification.

Prefix        cf

3.2 Identifying a List

This XML element allows the publisher of a feed document to indicate to the consumers of the feed that the feed is intended to be consumed as a list.

Syntax
   <cf:treatAs>list</cf:treatAs>

This element should be located in the feed as a child element of the RSS 2.0 <channel> element or the Atom <feed> element.

Example
   <rss>
     <channel>
      <cf:treatAs>list</cf:treatAs>
      <title>...</title>
      ...

The consumer of the feed should use this information to treat the content of the feed as if it represents a complete, ordered list of content from the server. This implies that the client should respect the order from the server, and assume that items that are missing from the list are no longer part of the list (and should be deleted from the local copy of the list, if one is maintained).

3.3 Lightweight Property Description

3.3.1 Overview

The Simple List Extensions include a set of XML elements which enable the publisher to indicate to the client which properties are useful for sorting and grouping (or filtering) purposes. These elements make reference to XML elements that are child-elements within the items of the same feed, using the supported extension mechanism of the feed format.

Syntax:
   <cf:listinfo>
     <cf:sort
       ns="namespace"
       element="element"
       data-type="date|text|number"  
       label="User-readable name for the sort field"
       default="true|false" />
     <cf:group
       ns="namespace"
       element="element"
       label="User-readable name for the grouping" />
   </cf:listinfo>

Details:
The cf:listinfo element may contain zero or more instances of either of two child-elements: cf:sort and cf:group.

Each instance of the cf:sort or cf:group element makes reference to a child-element which appears within each of the items of the feed. These elements may be considered properties of the item, and will be referred to as such below.

For example, an item that describes a book may contain include a property book:firstedition, that represents the date on which the first edition was published. Each item may also contain a book:genre property that describes the genre of the item.  In this example, the book prefix may be mapped to http://www.example.com/book.

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 text content of the element itself (i.e. the character data contained in the element). Values of attributes or nested elements cannot be used for sorting or grouping.
  
  
• 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.

This extension can be used on any type of feed -- i.e. a feed may contain cf:listinfo without containing cf:treatAs element (and vice versa).

3.3.2 Sorting

The cf:sort element is intended to inform the client that the property to which it refers is one that is “sortable” – that is, that the client should provide a user interface that allows the user to sort on that property.

The cf:sort element can also be used to provide a label for the default sort that appears in the list (in this case, only the label attribute should be included).

The cf:sort element contains the following attributes:

• ns - this attribute is the full namespace used in the property element. If the attribute value is an empty string, it is assumed that the property does not live in a namespace. If the ns attribute is omitted, the default value is the empty string. In the example above, the ns attribute would contain "http://www.example.com/book". It would not contain the namespace prefix.
• element - this attribute is the name of the property (without any namespace). In the example above, the element attribute would contain "firstedition" If this attribute is omitted, it is assumed that the label attribute is included and that this cf:sort element refers to the default sort order.
• label - this attribute contains a human-readable name for the property to which this cf:sort element refers. If it is omitted, the client should use the value of the "element" attribute as the human-readable name. The "label" attribute is required if the "element" attribute is omitted.
• data-type - this attribute informs the client about the data-type of the property to which this cf:sort element refers.. It contains one of the following values: date, number, text. If it is omitted, the default value is text.
• default - this attribute indicates whether the property to which this cf:sort element refers is the default sort order in the list. The allowed values are "true" and "false". If omitted, the default value is "false". The items in the list must be already be sorted by the element – this is, the client should not expect to have to resort by this field if it displaying content directly from the list. The client should respect only the first instance of default="true" that it encounters.

3.3.3 Grouping

The cf:group element is intended to inform the client that the property to which it refers is one that is “groupable” – that is, that the client should provide a user interface that allows the user to group or filter on the values of that property. Groupable properties should contain a small set of discrete values (e.g. book genres are perfect for groups).

The cf:group element contains the following attributes:

• ns - this attribute is the full namespace used in the property element. If the attribute value is an empty string, it is assumed that the property does not live in a namespace. If the ns attribute is omitted, the default value is the empty string. In the example above, the ns attribute would contain "http://www.example.com/book". It would not contain the namespace prefix.
• element - this attribute is the name of the property (without any namespace). In the example above, the element attribute would contain "firstedition" If this attribute is omitted, it is assumed that the label attribute is included and that this cf:group element refers to the default sort order.
• label - this attribute contains a human-readable name for the property to which this cf:group element refers. If it is omitted, the client should use the value of the "element" attribute as the human-readable name. The "label" attribute is required if the "element" attribute is omitted.  

4.    Additional Information

This specification is designed to be as simple as possible. Additional information, explanation and examples can be found at:
http://blogs.msdn.com/rssteam/articles/SimpleListExtensionsExplained.aspx 

5.    Revision History

        1.0 Original specification release.
        1.0a Updated spec to fix typos, add examples and improve clarity.

6.    License Information

Microsoft’s copyrights in this specification are licensed under the Creative Commons Attribution-ShareAlike License (version 2.5).  To view a copy of this license, please visit http://creativecommons.org/licenses/by-sa/2.5/.   As to software implementations, Microsoft is not aware of any patent claims it owns or controls that would be necessarily infringed by a software implementation that conforms to the specification’s extensions. If Microsoft later becomes aware of any such necessary patent claims, Microsoft also agrees to offer a royalty-free patent license on reasonable and non-discriminatory terms and conditions to any such patent claims for the purpose of publishing and consuming the extensions set out in the specification.