RSS 2.0 Specification

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 Character Data
- 3.2 Dates and Times
- 3.3 E-mail Addresses
- 3.4 URLs
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, also called a feed, must conform to the XML 1.0 specification and may contain elements and attributes defined in a namespace according to the Namespaces in XML specification.

RSS elements do not belong to a namespace. All elements in an RSS feed that are not defined in a namespace must be described in this specification. None of the restrictions described in this specification apply to elements or attributes defined in a namespace.

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

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

RSS feeds 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.

An RSS document is commonly described as a feed or newsfeed. Software designed to retrieve and present RSS feeds to users is called an aggregator, newsreader or reader. For clarity, this specification uses the terms feed and aggregator.

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 Character Data

For all elements defined in this specification that enclose character data, publishers should format the data 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.

Although some publishers employ HTML markup in other elements such as an item's title, using plain text in those elements achieves the widest support in aggregators.

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

3.2 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.3 E-mail Addresses

Several elements must contain an e-mail address, but there's no requirement to follow a specific format for such addresses. Publishers could format addresses according to the RFC 2822 Address Specification, the RFC 2368 guidelines for mailto links, or some other scheme.

The recommended format for e-mail addresses in RSS elements is username@hostname.tld (Real Name), as in the following example:

<managingEditor>luksa@dallas.example.com (Frank Luksa)</managingEditor>

3.4 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 feeds 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. All link and url elements must be valid URLs, so an IRI that contains non-ASCII characters must be converted to a URL using the procedure described in RFC 3987.

4. Elements

An RSS feed consists of the following elements.

4.1. rss

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

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 feed, providing such information as its title and description, and contains items that represent discrete updates to the web content represented by the feed.

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 holds character data that provides a human-readable characterization or summary of the feed (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 feed (required).

4.1.1.3 title

The title element holds character data that provides the name of the feed (required). If the feed corresponds directly to a web site, the title could 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 feed 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 could be a slash-delimited string that identifies a hierarchical position in the taxonomy.

<category domain="dmoz">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 feed 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 feed.
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 on port 80 using the 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 feed (optional).

The absence of the copyright element in a feed does not mean that the feed is in the public domain.

4.1.1.7 docs

The docs element identifies the URL of the RSS specification implemented by the software that created the feed (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 feed (optional).

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

<generator>http://www.sixapart.com/movabletype/?v=3.2</generator>

4.1.1.9 image

The image element supplies a graphical logo for the feed (optional).

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 could be the same URL as the channel's link element.

4.1.1.9.2 title

The image's title element holds character data that provides a human-readable description of the image (required). This could 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 (required). The URL must be in the GIF, JPEG or PNG formats.

4.1.1.9.4 description

The image's description element holds character data that 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). 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 width

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

The channel's language element identifies the natural language employed in the feed (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 that any of the feed's content was updated (optional).

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 feed (optional).

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

4.1.1.13 pubDate

The channel's pubDate element indicates the publication date and time of the feed's content (optional). Publishers of daily, weekly or monthly periodicals could use this element to associate feed items with the date they most recently went to press.

4.1.1.14 rating

The channel's rating element supplies an advisory label for the content in a feed, 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 "2007.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 feed is not updated (optional). On these days, the feed 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 feed is not updated (optional). During these hours, the feed 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 feed'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 holds character data that 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 feed's time to live (TTL): the number of minutes the feed can be cached (optional).

This element supports the distribution of RSS feeds on file-sharing networks such as Gnutella. Some aggregators won't check a feed more frequently than its TTL value, so a feed with a TTL of 90 would be checked no more often than once every 90 minutes.

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 feed (optional).

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

4.1.1.20 item

An item element represents distinct content published over the feed 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.

<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 feed published by an individual could omit this element and use the managingEditor or webMaster channel elements to provide contact information.

<author>jbb@dallas.example.com</author>

4.1.1.20.2 category

An item's category element identifies a category or tag to which the item belongs (optional). The requirements are the same as the channel's category element.

<category>rec.arts.movies.reviews</category>

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 holds character data that 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 should 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.

For best support in the widest number of aggregators, publishers should not include more than one enclosure in an item.

Because some popular RSS implementations support multiple enclosures, aggregators should expect to encounter feeds where more than one enclosure is present in an item. Aggregators may use their discretion to handle all of the enclosures or just the first enclosure present within an item.

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 feed's publisher has devised for ensuring the uniqueness of the string, such as the Tag URI scheme described in RFC 4151.

<guid isPermaLink="false">tag:dallas.example.com,4131:news</guid>

A publisher should provide a guid with each item. If the guid is a URL, it must conform with the specification's URL requirements.

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

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 feed (optional). The element must have a url attribute that identifies the URL of the source feed.

The value of the source could be the title of the source feed.

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

4.1.1.20.10 title

An item's title element holds character data that 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

Comments and corrections regarding this document are encouraged on the RSS Advisory Board's RSS-Public mailing list.

The RSS format was created by Dan Libby and Ramanathan Guha. Rogers Cadenhead, James Holderness, Randy Charles Morin and Greg Smith contributed to this document.