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:
- 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).
- 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).
- 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.