RSS Specification (Proposed)

Really Simple Syndication Specification

Editor's Note: This proposed specification provides new documentation for the Really Simple Syndication format, describing exactly the same elements and attributes delineated in RSS 2.0 Specification (Current), published by the RSS Advisory Board on March 30, 2009. RSS documents that conform to this specification also conform to its predecessor. This is a draft document. Visit this link for the current RSS Specification.

Copyright Notice

1 Introduction
2 Conventions
3 Data Types
- 3.1 Dates and Times
- 3.2 URLs
- 3.3 Character Data
4 Elements
- 4.1 rss
  - 4.1.1 channel
    - 4.1.1.1 description
    - 4.1.1.2 link
    - 4.1.1.3 title
    - 4.1.1.4 category
    - 4.1.1.5 cloud
    - 4.1.1.6 copyright
    - 4.1.1.7 docs
    - 4.1.1.8 generator
    - 4.1.1.9 image
      - 4.1.1.9.1 link
      - 4.1.1.9.2 title
      - 4.1.1.9.3 url
      - 4.1.1.9.4 description
      - 4.1.1.9.5 height
      - 4.1.1.9.6 width
    - 4.1.1.10 language
    - 4.1.1.11 lastBuildDate
    - 4.1.1.12 managingEditor
    - 4.1.1.13 pubDate
    - 4.1.1.14 rating
    - 4.1.1.15 skipDays
      - 4.1.1.15.1 day
    - 4.1.1.16 skipHours
      - 4.1.1.16.1 hour
    - 4.1.1.17 textInput
      - 4.1.1.17.1 description
      - 4.1.1.17.2 link
      - 4.1.1.17.3 name
      - 4.1.1.17.4 title
    - 4.1.1.18 ttl
    - 4.1.1.19 webMaster
    - 4.1.1.20 item
      - 4.1.1.20.1 author
      - 4.1.1.20.2 category
      - 4.1.1.20.3 comments
      - 4.1.1.20.4 description
      - 4.1.1.20.5 enclosure
      - 4.1.1.20.6 guid
      - 4.1.1.20.7 link
      - 4.1.1.20.8 pubDate
      - 4.1.1.20.9 source
      - 4.1.1.20.10 title
5. License
6. Credits
7. To Do

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.

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.

RSS elements do not belong to a namespace. All elements in an RSS document that are not defined in a namespace must be described in this specification.

This specification describes the current version of the RSS format, which follows versions 0.91 and 0.92.

A sample document demonstrates all of the elements available in RSS. A namespace sample shows the same document extended by the Creative Commons and TrackBack namespaces.

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.

3. Data Types

The requirements for RSS 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 link and url elements, 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 of RSS documents must not assume that all schemes are available.

3.3 Character Data

For all elements defined in this specification that enclose character data, the text must be interpreted as plain text with the exception of an item's description element, which must be suitable for presentation as 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 RSS element.

4. Elements

An RSS document consists of the following elements.

4.1. rss

The rss element is the top-level element of an RSS document. A document that conforms to this specification must contain a version attribute with the value "2.0.2".

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 elements: category, cloud, copyright, docs, generator, image, language, lastBuildDate, managingEditor, pubDate, rating, skipDays, skipHours, textInput, ttl and webMaster.

The preceding elements must not be present more than once in a channel, with the exception of 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>

4.1.1.2 link

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

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 category

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

<category>Media</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.

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

A channel may contain more than one category element.

4.1.1.5 cloud

The 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.

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 a namespace.

4.1.1.6 copyright

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

4.1.1.7 docs

The docs element identifies the URL of the RSS specification implemented by the software that created the channel (optional). The permanent URL for the specification you are reading is https://www.rssboard.org/rss-specification.

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

4.1.1.8 generator

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

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

4.1.1.9 image

The image element supplies a graphical logo for the channel (optional). This image must be no larger than 144 pixels wide and 400 pixels tall.

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

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

4.1.1.9.1 link

The image's 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 title

The image's 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 url

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

4.1.1.9.4 description

The image's 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 height

The image's height element contains the height, in pixels, of the image (optional). If this element is omitted, the image is assumed to be 31 pixels tall.

4.1.1.9.6 width

The image's width element contains the width, in pixels, of the image (optional). If this element is omitted, the image is assumed to be 88 pixels wide.

4.1.1.10 language

The channel's 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.

4.1.1.11 lastBuildDate

The channel's 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.

4.1.1.12 managingEditor

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

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

4.1.1.13 pubDate

The channel's 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.

4.1.1.14 rating

The channel's 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).

<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))</rating>

4.1.1.15 skipDays

The channel's 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 day elements identifying the days to skip.

4.1.1.15.1 day

The 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.

<skipDays>
<day>Saturday</day>
<day>Sunday</day>
</skipDays>

4.1.1.16 skipHours

The channel's 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 hour elements identifying the hours to skip.

4.1.1.16.1 hour

The 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.

4.1.1.17 textInput

The 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 description, link, name and title child element.

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

4.1.1.17.1 description

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

4.1.1.17.2 link

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

4.1.1.17.3 name

The input form's 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 title

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

4.1.1.18 ttl

The channel's 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).

4.1.1.19 webMaster

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

<webMaster>helpdesk@dallas.example.com</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 child elements: author, category, comments, description, enclosure, guid, link, pubDate, source and title. All of these elements are optional but an item must contain either a title or description.

The preceding elements must not be present more than once in an item, with the exception of category.

<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>
</item>

4.1.1.20.1 author

An item's 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 managingEditor or webMaster channel elements to provide contact information.

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

4.1.1.20.2 category

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

<category>movies</category>

This element may include a 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.

An item may contain more than one category element.

4.1.1.20.3 comments

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

<comments>http://dallas.example.com/feedback/1983/06/joebob.htm</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 < ("<") and > (">") or a CDATA section.

Escaped markup created with character entities:

<description>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.</description>

CDATA encoding:

<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.]]></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 enclosure

An item's 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

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

4.1.1.20.6 guid

An item's 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.

<guid>http://dallas.example.com/1983/05/06/joebob.htm</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.

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

A publisher should provide a guid with each item.

4.1.1.20.7 link

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

4.1.1.20.8 pubDate

An item's 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.

4.1.1.20.9 source

An item's 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.

<source url="http://la.example.com/rss.xml">Los Angeles Herald-Examiner</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

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.