XRSS Specification

Editor's Note: This proposed specification provides documentation for XRSS, a namespace for the Really Simple Syndication format documented in RSS 2.0.1 (revision 6). Public comments on this proposed specification, which is still in active development and has not been officially adopted by the RSS Advisory Board or any other group, are welcomed on the mailing list RSS-Public.

Copyright 2006 RSS Advisory Board. This is draft version 1.11 of this document, published March 7, 2006. The current version will always be available at this link, and other drafts are available.

Table of Contents

1. Introduction

Really Simple Syndication (RSS) is an XML-based document format for the syndication of web content so that it can be republished on other sites or downloaded periodically and presented to users. The RSS 2.0 specification describes how to create RSS documents.

An RSS document must conform to the XML 1.0 specification and may contain elements defined in a namespace according to the Namespaces in XML specification.

This specification describes one such namespace, XRSS, and provides guidance on how to create RSS documents for the wide and diverse audience of client software that supports the format.

A sample document demonstrates all of the elements available in an RSS document that has been extended with the XRSS namespace. Another sample shows how the same document can be extended by other namespaces such as Creative Commons and TrackBack.

RSS documents that support XRSS can be tested for validity in the Feed Validator.

2. Conventions

In this specification, the key words may, must, must not, optional, recommended, required, shall, shall not, should and should not are to be interpreted as described in RFC 2119.

Software designed to retrieve and present RSS documents to users is called an aggregator, newsreader or reader. For clarity, this specification uses the term aggregator exclusively.

For simplicity, in the rest of this specification, RSS documents that support the XRSS namespace will be described as "XRSS documents" and elements from the XRSS namespace are called "XRSS elements."

3. Data Types

The requirements for XRSS element and attribute values are defined in the sections devoted to each element, aside from the following restrictions.

3.1 Dates and Times

All date-time values must conform to the RFC 822 Date and Time Specification with the exception that a four-digit year is permitted and recommended over a two-digit year.

3.2 URLs

In all elements whose value represents a URL, such as xrss:link and xrss:url, the first non-whitespace characters in a URL must begin with a scheme defined by the IANA Registry of URI Schemes such as "ftp://", "http://", "https://", "mailto:" or "news://". These elements must not contain relative URLs.

Because an aggregator may choose which URI schemes to support, publishers must not assume that all schemes are available.

An Internationalized Resource Identifier (IRI) provides a means to identify Internet resources using non-ASCII characters that can't be present in URLs. An IRI that contains non-ASCII characters MUST be converted to a URL using the procedure described in RFC 3987.

3.3 Character Data

For all elements defined in this specification that enclose character data, the text must be interpreted as plain text rather than HTML. All of these elements must not contain child elements.

There's no limit on the length of character data that can be contained in an XRSS element.

4. Elements

An XRSS document consists of five required RSS elements, two required RSS elements for each item and zero or more optional XRSS elements.

The definitions of the RSS elements in this specification are provided for convenience and must not be treated as definitive. Refer to the RSS 2.0 specification for authorititive guidance on the format.

All elements of an XRSS document that are not contained in a namespace must be described in this specification. All recommendations offered for RSS elements in this specification should be followed in XRSS documents.

4.1. rss

The rss element is the top-level element of an RSS document and must contain a version attribute with the value "2.0". To indicate compliance with the XRSS specification, an RSS document must declare the XRSS namespace with an xmlns attribute with the URI https://www.rssboard.org/xrss:

<rss version="2.0" xmlns:xrss="https://www.rssboard.org/xrss">

This element is required and must contain a channel element. The rss element must not contain more than one channel.

4.1.1 channel

The channel element describes the RSS document (also called a channel), providing such information as its title and description, and contains items that represent discrete updates to the web content represented by the document.

This element is required and must contain three child elements: description, link and title.

The channel may contain each of the following optional XRSS elements: xrss:category, xrss:cloud, xrss:copyright, xrss:docs, xrss:generator, xrss:image, xrss:language, xrss:lastBuildDate, xrss:managingEditor, xrss:pubDate, xrss:rating, xrss:skipDays, xrss:skipHours, xrss:textInput, xrss:ttl and xrss:webMaster.

The preceding XRSS elements must not be present more than once in a channel, with the exception of xrss:category.

The channel also may contain zero or more item elements, which should appear after all of the other channel elements defined in this specification.

Otherwise, the order of elements within the channel is not significant.

4.1.1.1 description

The description element provides a human-readable characterization or summary of the channel (required).

<description>Current headlines from the Dallas Times-Herald newspaper</description>

The link element identifies the URL of the web site associated with the channel (required).

<link>http://dallas.example.com</link>

The URL must follow the same rules as XRSS elements that hold URL values.

4.1.1.3 title

The title element provides the name of the channel (required). If the channel corresponds directly to a web site, the name should match the name of the site.

<title>Dallas Times-Herald</title>

4.1.1.4 xrss:category

The xrss:category element identifies a category or tag to which the channel belongs (optional).

<xrss:category>Media</xrss:category>

This element may include a domain attribute that identifies the taxonomy in which the category is placed. The category's value should be a slash-delimited string that identifies a hierarchical position in the taxonomy.

<xrss:category domain="dmoz">News/Newspapers/Regional/United_States/Texas</xrss:category>

A channel may contain more than one category element.

4.1.1.5 xrss:cloud

The xrss:cloud element indicates that updates to the channel can be monitored using a web service that implements the RssCloud application programming interface (optional).

The element must have five attributes that describe the service:

  • The domain attribute identifies the host name or IP address of the web service that monitors updates to the channel.
  • The path attribute provides the web service's path.
  • The port attribute identifies the web service's TCP port.
  • The protocol attribute must contain the value "xml-rpc" if the service employs XML-RPC or "soap" if it employs SOAP.
  • The registerProcedure attribute names the remote procedure to call when requesting notification of updates.

<xrss:cloud domain="server.example.com" path="/rpc" port="80" protocol="xml-rpc" registerProcedure="cloud.notify" />

In this example, an aggregator could request notification by calling the cloud.notify method of the XML-RPC web service at server.example.com, port 80, path /rpc.

This element is an empty element defined by a single tag and its attributes, unless extended by another namespace.

The xrss:copyright element declares the human-readable copyright statement that applies to the channel (optional).

<xrss:copyright>Copyright 2006 Dallas Times-Herald</xrss:copyright>

4.1.1.7 xrss:docs

The xrss:docs element identifies the URL of the RSS specification implemented by the software that created the channel (optional)..

<docs>https://www.rssboard.org/rss-specification</docs>

This element must not refer to this specification, which documents the XRSS namespace.

4.1.1.8 xrss:generator

The xrss:generator element credits the software that created the channel (optional).

<xrss:generator>Radio UserLand v8.2.1</xrss:generator>

4.1.1.9 xrss:image

The xrss:image element supplies a graphical logo for the channel (optional).

The image must contain three child elements: xrss:link, xrss:title and xrss:url. It also may contain three optional elements: xrss:description, xrss:height and xrss:width.

<xrss:image>
  <xrss:link>http://dallas.example.com</xrss:link>
  <xrss:title>Dallas Times-Herald</xrss:title>
  <xrss:url>http://dallas.example.com/masthead.gif</xrss:url>
  <xrss:description>Read the Dallas Times-Herald</xrss:description>
  <xrss:height>32</xrss:height>
  <xrss:width>96</xrss:width>
</xrss:image>

The image's xrss:link element identifies the URL of the web site represented by the image (required). This should be the same URL as the channel's link element.

4.1.1.9.2 xrss:title

The image's xrss:title element provides a human-readable description of the image (required). This should be the same text as the channel's title element and is suitable for use as the alt attribute of the img tag in an HTML rendering.

4.1.1.9.3 xrss:url

The image's xrss:url element identifies the URL of the image, which must be in the GIF, JPEG or PNG formats (required).

4.1.1.9.4 xrss:description

The image's xrss:description element provides a human-readable characterization of the site linked to the image (optional). The description is suitable for use as the title attribute of the a tag in an HTML rendering.

4.1.1.9.5 xrss:height

The image's xrss:height element contains the height, in pixels, of the image (optional). The image must be no taller than 400 pixels. If this element is omitted, the image is assumed to be 31 pixels tall.

4.1.1.9.6 xrss:width

The image's xrss:width element contains the width, in pixels, of the image (optional). The image must be no wider than 144 pixels. If this element is omitted, the image is assumed to be 88 pixels wide.

4.1.1.10 xrss:language

The channel's xrss:language element identifies the natural language employed in the channel (optional).

The language must be identified using one of the RSS language codes or a language code permitted by the World Wide Web Consortium for use in HTML. The U.S. Library of Congress publishes the current list of ISO 639 language codes adopted by HTML.

<xrss:language>epo</xrss:language>

4.1.1.11 xrss:lastBuildDate

The channel's xrss:lastBuildDate element indicates the last date and time the content of the channel was updated (optional). The value must conform with this specification's requirement for date-time data.

<xrss:lastBuildDate>Sun, 29 Jan 2006 17:17:44 GMT</xrss:lastBuildDate>

4.1.1.12 xrss:managingEditor

The channel's xrss:managingEditor element provides the e-mail address of the person to contact regarding the editorial content of the channel (optional).

<xrss:managingEditor>jlehrer@dallas.example.com (Jim Lehrer)</xrss:managingEditor>

4.1.1.13 xrss:pubDate

The channel's xrss:pubDate element indicates the publication date of the channel's content (optional). The value must conform with the specification's requirement for date-time data.

<xrss:pubDate>Sun, 29 Jan 2006 05:00:00 GMT</xrss:pubDate>

4.1.1.14 xrss:rating

The channel's xrss:rating element supplies an advisory label for the content in a channel, formatted according to the specification for the Platform for Internet Content Selection (PICS) (optional).

<xrss:rating>(PICS-1.1 "http://www.rsac.org/ratingsv01.html" l by "webmaster@example.com" on "2006.01.29T10:09-0800" r (n 0 s 0 v 0 l 0))</xrss:rating>

4.1.1.15 xrss:skipDays

The channel's xrss:skipDays element identifies days of the week during which the channel is not updated (optional). On these days, the channel should not be requested by an aggregator. This element contains up to seven xrss:day elements identifying the days to skip.

4.1.1.15.1 xrss:day

The xrss:day element identifies a weekday in Greenwich Mean Time (GMT) (required). Seven values are permitted -- "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" or "Sunday" -- and must not be duplicated.

<xrss:skipDays>
  <xrss:day>Saturday</xrss:day>
  <xrss:day>Sunday</xrss:day>
</xrss:skipDays>

4.1.1.16 xrss:skipHours

The channel's xrss:skipHours element identifies the hours of the day during which the channel is not updated (optional). During these hours, the channel should not be requested by an aggregator. This element contains individual xrss:hour elements identifying the hours to skip.

4.1.1.16.1 xrss:hour

The xrss:hour element identifies an hour of the day in Greenwich Mean Time (GMT) (required). The hour must be expressed as an integer representing the number of hours since 00:00:00 GMT. Values from 0 to 24 are permitted, with either 0 or 24 representing midnight. An hour must not be duplicated.

<xrss:skipHours>
  <xrss:hour>0</xrss:hour>
  <xrss:hour>1</xrss:hour>
  <xrss:hour>2</xrss:hour>
  <xrss:hour>22</xrss:hour>
  <xrss:hour>23</xrss:hour>
</xrss:skipHours>

4.1.1.17 xrss:textInput

The xrss:textInput element defines a form to submit a text query to the channel's publisher over the Common Gateway Interface (CGI) (optional).

The element must contain a xrss:description, xrss:link, name and xrss:title child element.

<xrss:textInput>
  <xrss:description>Your aggregator supports the textInput element. What software are you using?</xrss:description>
  <xrss:link>http://www.cadenhead.org/textinput.php</xrss:link>
  <xrss:name>query</xrss:name>
  <xrss:title>TextInput Inquiry</xrss:title>
</xrss:textInput>

4.1.1.17.1 xrss:description

The input form's xrss:description element provides a human-readable label explaining the form's purpose (required).

The input form's xrss:link element identifies the URL of the CGI script that handles the query (required).

4.1.1.17.3 xrss:name

The input form's xrss:name element provides the name of the form component that contains the query (required). The name must begin with a letter and contain only these characters: the letters A to Z in either case, numeric digits, colons (":"), hyphens ("-"), periods (".") and underscores ("_").

4.1.1.17.4 xrss:title

The input form's xrss:title element labels the button used to submit the query (required).

4.1.1.18 xrss:ttl

The channel's xrss:ttl element represents the channel's time to live: the number of minutes it can be cached before another request should be made by an aggregator (optional).

<xrss:ttl>60</xrss:ttl>

4.1.1.19 xrss:webMaster

The channel's xrss:webMaster element provides the e-mail address of the person to contact about technical issues regarding the channel (optional).

<xrss:webMaster>helpdesk@dallas.example.com</xrss:webMaster>

4.1.1.20 item

An item element represents distinct content published over the channel such as a news article, weblog entry or some other form of discrete update. A channel may contain any number of items (or no items at all).

An item may contain the following XRSS child elements: xrss:author, xrss:category, xrss:comments, description, xrss:enclosure, xrss:guid, xrss:link, xrss:pubDate, xrss:source and title. All of these elements are optional but an item must contain either a title or description.

The RSS elements description and title must not be present more than once in an item.

XRSS elements must not be present more than once in an item, with the exception of xrss:category and xrss:enclosure.

<item>
  <title>Seventh Heaven! Ryan Hurls Another No Hitter</title>
  <link>http://dallas.example.com/1991/05/02/nolan.htm</link>
  <description>Texas Rangers pitcher Nolan Ryan hurled the seventh no-hitter of his legendary career on Arlington Appreciation Night, defeating the Toronto Blue Jays 3-0. The 44-year-old struck out 16 batters before a crowd of 33,439.</description>
  <xrss:guid isPermaLink="false">1983-05-06+lifestyle+joebob</xrss:guid>
</item>

4.1.1.20.1 xrss:author

An item's xrss:author element provides the e-mail address of the person who wrote the item (optional). A channel published by an individual should omit this element and use the xrss:managingEditor or xrss:webMaster channel elements to provide contact information.

<xrss:author>jbb@dallas.example.com (Joe Bob Briggs)</xrss:author>

4.1.1.20.2 xrss:category

An item's xrss:category element identifies a category or tag to which the item belongs (optional).

<xrss:category>movies</xrss:category>

This element may include a xrss:domain attribute that identifies the category's taxonomy. The category's value should be a slash-delimited string that identifies a hierarchical position in the taxonomy.

<xrss:category domain="rec.arts.movies.reviews">1983/V</xrss:category>

An item may contain more than one category.

4.1.1.20.3 xrss:comments

An item's xrss:comments element identifies the URL of a web page that contains comments received in response to the item (optional).

<xrss:comments>http://dallas.example.com/feedback/1983/06/joebob.htm</xrss:comments>

4.1.1.20.4 description

An item's description element contains the item's full content or a summary of its contents, a decision entirely at the discretion of the publisher. This element is optional if the item contains a title element.

<description>I'm headed for France. I wasn't gonna go this year, but then last week "Valley Girl" came out and I said to myself, Joe Bob, you gotta get out of the country for a while.</description>

The description must be suitable for presentation as HTML. HTML markup must be encoded as character data either by employing the HTML entities &lt; ("<") and &gt; (">") or a CDATA section.

Escaped markup created with character entities:

<xrss:description>I'm headed for France. I wasn't gonna go this year, but then last week &lt;a href="http://www.imdb.com/title/tt0086525/"&gt;Valley Girl&lt;/a&gt; came out and I said to myself, Joe Bob, you gotta get out of the country for a while.</xrss:description>

CDATA encoding:

<xrss:description><![CDATA[I'm headed for France. I wasn't gonna go this year, but then last week <a href="http://www.imdb.com/title/tt0086525/">Valley Girl</a> came out and I said to myself, Joe Bob, you gotta get out of the country for a while.]]></xrss:description>

The description should not contain relative URLs. When a relative URL is present, an aggregator may attempt to resolve it to a full URL using the channel's link as the base.

4.1.1.20.5 xrss:enclosure

An item's xrss:enclosure element associates a media object such as an audio or video file with the item (optional). The element must have three attributes:

  • The length attribute indicates the size of the file in bytes
  • The type attribute identifies the file's MIME media type
  • The url attribute identifies the URL of the file

<xrss:enclosure length="24986239" type="audio/mpeg" url="http://dallas.example.com/joebob_050689.mp3" />

The xrss:enclosure element is an empty element defined by a single tag and its attributes, unless extended by a namespace.

An item may contain more than one enclosure.

4.1.1.20.6 xrss:guid

An item's xrss:guid element provides a string that uniquely identifies the item (optional). The guid may include an isPermaLink attribute.

The guid enables an aggregator to detect when an item has been received previously and does not need to be presented to a user again. If the guid's isPermaLink attribute is omitted or has the value "true", the guid must be the permanent URL of the web page associated with the item.

<xrss:guid>http://dallas.example.com/1983/05/06/joebob.htm</xrss:guid>

If the guid's isPermaLink attribute has the value "false", the guid may employ any syntax the channel's publisher has devised for ensuring the uniqueness of the string.

<xrss:guid isPermaLink="false">1983-05-06+lifestyle+joebob</xrss:guid>

A publisher should provide a guid with each item. When a guid represents a permalink, it should take precedence over the item's link.

An item's xrss:link element identifies the URL of a web page associated with the item (optional).

<xrss:link>http://dallas.example.com/1983/05/06/joebob.htm</xrss:link>

4.1.1.20.8 xrss:pubDate

An item's xrss:pubDate element indicates the publication date and time of the item (optional). The value must conform with this specification's rule for date-time data.

If the publication date occurs in the future, aggregators may ignore the item until the date and time has passed.

<xrss:pubDate>Fri, 06 May 1983 09:00:00 CST</xrss:pubDate>

4.1.1.20.9 xrss:source

An item's xrss:source element indicates the fact that the item has been republished from another RSS channel (optional). The element must have a url attribute that identifies the URL of the source channel.

The value of the source is the title of the source channel.

<xrss:source url="http://la.example.com/rss.xml">Los Angeles Herald-Examiner</xrss:source>

4.1.1.20.10 title

An item's title element provides the item's headline. This element is optional if the item contains a description element.

<title>Joe Bob Goes to the Drive-In</title>

5. License

Copyright 2006 RSS Advisory Board. The copyright applies to the XRSS namespace, not to the RSS specification or the data format that the RSS specification describes.

6. Credits

The author of this specification is the RSS Advisory Board. Comments and corrections regarding this document are encouraged on the RSS-Public mailing list.

The RSS format was created by Dan Libby and Dave Winer.

7. To Do

The following known issues have not been resolved as of this draft of the specification.

  • Should a supplementary appendix be added that covers the most commonly used namespaced elements?
  • Adding documentation on how to create RFC 822-plus-four-year date-time values

This section will be removed upon the final publication of this document.

RSS icon

Main Menu
RSS Advisory Board
RSS Specification
RSS Profile
RSS Validator
RSS Autodiscovery
Board Members
Charter
RSS-Public Mailing List
RSS Language Codes
RSSCloud Interface
RSS History
RSS Feeds
Subscribe to Really Simple Syndication This Weblog
Social Media
Mastodon
Spec Library
RSS 2.0 (Current)
RSS 2.0
RSS 0.92
RSS 0.91 (UserLand)
RSS 0.91 (Netscape)
RSS 0.90
RSS Change Notes
Namespaces
Creative Commons
Media RSS
Trackback
Archive
Site Index
Board Members
Rogers Cadenhead
Sterling "Chip" Camden
Simone Carletti
James Holderness
Jenny Levine
Eric Lunt
Randy Charles Morin
Ryan Parman
Jake Savin
Jason Shellen
Paul Querna
Other Formats
Atom
RDF Site Summary

Popular Pages on This Site

RSS Advisory Board | RSS Feed | RSS Specification | Hosted by Workbench