OpenSearch™ RSS 1.0

"The OpenSearch RSS extension aims to define the bare minimum of additional functionality required to provide search results over RSS channels."

OpenSearch RSS 1.0 is an extension to the RSS 2.0 standard, conforming to the guidelines for RSS extensibility as outlined by the RSS 2.0 specification. The intent is to provide a standard format for returning results for a search query. This extension is designed to be backward compatible with existing RSS readers.

Version 1.0 of OpenSearch RSS adds only three new elements, each within the openSearch XML namespace. Additionally, OpenSearch 1.0 makes recommendations on how existing RSS 2.0 elements can be best used within a search context.

Future versions of OpenSearch RSS will attempt to maintain backwards compatibility with OpenSearch RSS 1.0. More complicated search extensions to RSS 2.0, such as language selection, encoding type, spelling suggestions, multi-media results, sponsored links, etc, will be done in such a way as to keep OpenSearch RSS easy to implement and interpret.

An example OpenSearch RSS 1.0 search result document would look like:

  <?xml version="1.0"?>
  <rss version="2.0" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
    <channel>
      <title>A9.com Search: New York City history</title>
      <link>http://a9.com/New%20York%20City%20history</link>
      <description>Search results for "New York City history" at A9.com</description>
      <language>en-us</language>
      <copyright>&amp;copy;2003-2005, A9.com, Inc. or its affiliates.</copyright>
      <openSearch:totalResults>4230000</openSearch:totalResults>
      <openSearch:startIndex>1</openSearch:startIndex>
      <openSearch:itemsPerPage>10</openSearch:itemsPerPage>

      <item>
        <title>New York City History</title>
        <link>http://www.columbia.edu/cu/lweb/eguides/amerihist/nyc.html</link>
        <description>... Harlem.NYC - A virtual tour and information on 
        businesses ...  with historic photos of Columbia's own New York 
        neighborhood ... Internet Resources for the City's History. ...</description>
      </item>
      <item>
        <title>Gotham Center for New York City History</title>
        <link>http://www.gothamcenter.org/</link>
        <description>... Submit Events Edit Your Submission. Main Neighborhood
        Stories NYC History in the ... The Gotham Center for New York City History
        is supported by The CUNY Graduate ...</description>
      </item>
      <!-- ... -->
      <item>
        <title>Welcome to the Museum of the City of New York</title>
        <link>http://www.mcny.org/</link>
        <description>... a list with the event staff. Additional information
        will be included in the confirming email. &copy; Museum of the City
        of New York.</description>
      </item>
    </channel>
  </rss>

The XML Namespace:

The openSearch namespace is specified as an attribute of the opening <rss/> element. The location of this XML schema is:

http://a9.com/-/spec/opensearchrss/1.0/

Thus the xmlns declaration in the opening rss element appears as follows:

  <rss version="2.0" xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">...</rss>

List of OpenSearch elements introduced by this specification:

openSearch:totalResults – The number of search results available.
- Parent: channel
- Note: If no results are available, the server should respond with 0.
  For example: <openSearch:totalResults>0</openSearch:totalResults>
- Optional, if this does not appear the client should assume all search results were returned in this request.

openSearch:startIndex – The index of the first item returned in the result, starting with 1.
- Parent: channel
- Optional, if this does not appear the client should assume that the first index returned is 1.

openSearch:itemsPerPage – The maximum number of items that appear on one page.
- Parent: channel
- Optional, if this does not appear the client should that 10 items are returned per page.

List of standard RSS elements given enhanced meaning by this specification:

title – The name of the search result provider.
- Parent: channel
- Notes: Should contain the search terms themselves.
- Restrictions: Can not contain HTML markup.
- Required

link – A URL to the website that providers the search results.
- Parent: channel
- Notes: Should return a URL that can recreate the search in HTML format.
- Restrictions: Can not contain HTML markup.
- Required

description – Phrase or sentence describing the search.
- Parent: channel
- Restriction: Can contain simple escaped HTML markup, such as <b> and <i> elements.
- Required

title – The text title of the search result.
- Parent: item
- Restrictions: Can not contain HTML markup.
- Optional. In practice, this should always exist.

link – The URL pointing to the content referred to in the search result.
- Parent: item
- Restrictions: Can not contain HTML markup.
- Optional. However, at least one of either link or description must exist, and usually both elements do.

description – A text snippet describing the search result.
- Parent: item
- Restriction: Can contain simple escaped HTML markup, such as <b>, <i>, <a>, and <img> elements.
- Optional. However, at least one of either link or description must exist, and usually both elements do.

For more information, please see: