Simple List Extensions Specification

  • Article

Simple List Extensions Specification

This specification was previously published on the XML Developer Center.

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

Contents:

  • 1. Overview 
    • 1.1 Background 
  • 2. Example 
  • 3. Simple List Extensions 
    • 3.1 Namespace 
    • 3.2 Identifying a List 
    • 3.3 Lightweight Property Description 
  • 4. Additional Information 
  • 5. Revision History 
  • 6. 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. For additional information and examples, see Simple List Extensions Explained (RSS Blog).

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="https://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 https://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 version="2.0" 
      xmlns:cf="https://www.microsoft.com/schemas/rss/core/2005">
     <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:

Attributes Description
ns 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 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 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 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 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:

Attributes Description
ns 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 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 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: https://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.