Atom Syndication Format – Introduction

Developers > Syndication

Contents

• What is Atom?
  • About this document
  • Sample feed
• Feed Elements
  • Required
  • Recommended
  • Optional
• Entry Elements
  • Required
  • Recommended
  • Optional
• Common Constructs
  • Category
  • Content
  • Link
  • Person
  • Text
• Extending Atom
• See Also

What is Atom?

Atom is the name of an XML-based Web content and metadata syndication format, and an application-level protocol for publishing and editing Web resources belonging to periodically updated websites.

All Atom feeds must be well-formed XML documents, and are identified with the application/atom+xml media type.

About this document
This document focuses on The Atom Syndication Format produced by the IETF AtomPub Working Group. In the event that this document differs from the Internet Draft, the Internet Draft is to be considered authoritative.

General considerations:

• All elements described in this document must be in the http://www.w3.org/2005/Atom namespace.
• All timestamps in Atom must conform to RFC 3339.
• Unless otherwise specified, all values must be plain text (i.e., no entity-encoded html).
• xml:lang may be used to identify the language of any human readable text.
• xml:base may be used to control how relative URIs are resolved.

Sample feed

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">

  <title>Example Feed</title>
  <link href="http://example.org/"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author>
    <name>John Doe</name>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

  <entry>
    <title>Atom-Powered Robots Run Amok</title>
    <link href="http://example.org/2003/12/13/atom03"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <summary>Some text.</summary>
  </entry>

</feed>

Elements of <feed>

A Feed consists of some metadata, followed by any number of entries.

Required feed elements
Here’s a list of the required feed elements, each with a brief description, and an example.

<id>http://example.com/</id>

<title>Example, Inc.</title>

<updated>2003-12-13T18:30:02Z</updated>

Recommended feed elements
Atom makes a number of additional requirements and recommendations for feed elements that you should to be aware of. They are as follows:

<author>
  <name>John Doe</name>
  <email>JohnDoe@example.com</email>
  <uri>http://example.com/~johndoe</uri>
</author>

<link rel="self" href="/feed" />

Optional feed elements

Here’s a list of optional feed elements.

<category term="sports"/>

<contributor>
  <name>Jane Doe</name>
</contributor>

<generator uri="/myblog.php" version="1.0">
  Example Toolkit
</generator>

<icon>/icon.jpg</icon>

<logo>/logo.jpg</logo>

<rights> © 2005 John Doe </rights>

<subtitle>all your examples are belong to us</subtitle>

Elements of <entry>

An example of an entry would be a single post on a weblog.

Required Elements of <entry>
Here’s a list of the required feed elements, each with a brief description, and an example.

<id>http://example.com/blog/1234</id>

<title>Atom-Powered Robots Run Amok</title>

<updated>2003-12-13T18:30:02-05:00</updated>

Recommended elements of <entry>
Atom makes a number of additional requirements and recommendations for entry elements that you should to be aware of. They are as follows:

<author>
  <name>John Doe</name>
</author>

<content>complete story here</content>

<link rel="alternate" href="/blog/1234"/>

<summary>Some text.</summary>

Optional elements of <entry>
Here’s a list of optional feed elements.

<category term="technology"/>

<contributor>
  <name>Jane Doe</name>
</contributor>

<published>2003-12-13T09:17:51-08:00</published>

<source>
  <id>http://example.org/</id>
  <title>Fourty-Two</title>
  <updated>2003-12-13T18:30:02Z</updated>
  <rights>© 2005 Example, Inc.</rights>
</source>

<rights type="html">
  &amp;copy; 2005 John Doe
</rights>

Common Constructs

Category
<category> has one required attribute, term, and two optional attributes, scheme and label.
term identifies the category
scheme identifies the categorization scheme via a URI.
label provides a human-readable label for display

Content
<content> either contains, or links to, the complete content of the entry.

In the most common case, the type attribute is either text, html, xhtml, in which case the content element is defined identically to other text constructs, which are described here.

Otherwise, if the src attribute is present, it represents the URI of where the content can be found. The type attribute, if present, is the media type of the content.

Otherwise, if the type attribute ends in +xml or /xml, then an xml document of this type is contained inline.

Otherwise, if the type attribute starts with text, then an escaped document of this type is contained inline.

Otherwise, a base64 encoded document of the indicated media type is contained inline.

Link
<link> is patterned after html’s link element. It has one required attribute, href, and five optional attributes: rel, type, hreflang, title, and length.

href is the URI of the referenced resource (typically a Web page)

rel contains a single link relationship type. It can be a full URI (see extensibility), or one of the following predefined values (default=alternate):

• alternate: an alternate representation of the entry or feed, for example a permalink to the html version of the entry, or the front page of the weblog.
• enclosure: a related resource which is potentially large in size and might require special handling, for example an audio or video recording.
• related: an document related to the entry or feed.
• self: the feed itself.
• via: the source of the information provided in the entry.

type indicates the media type of the resource.

hreflang indicates the language of the referenced resource.

title human readable information about the link, typically for display purposes.

length the length of the resource, in bytes.

Person
<author> and <contributor> describe a person, corporation, or similar entity. It has one required element, name, and two optional elements: uri, email.

<name> conveys a human-readable name for the person.

<uri> contains a home page for the person.

<email> contains an email address for the person.

Text
<title>, <summary>, <content>, and <rights> contain human-readable text, usually in small quantities. The type attribute determines how this information is encoded (default=”text”)

If type="text", then this element contains plain text with no entity escaped html.

<title type="text">AT&amp;T bought by SBC!</title>

If type="html", then this element contains entity escaped html.

<title type="html">
  AT&amp;amp;T bought &lt;b&gt;by SBC&lt;/b&gt;!
</title>

If type="xhtml", then this element contains inline xhtml, wrapped in a div element.

<title type="xhtml">
  <div xmlns="http://www.w3.org/1999/xhtml">
    AT&amp;T bought <b>by SBC</b>!
  </div>
</title>

Extending Atom

The atom content element is designed to support the direct inclusion of other XML vocabularies.

Any fully qualified URI may be used a value for the rel attribute of link elements.

Elements from other namespaces may be included pretty much anywhere. This means that most RSS 1.0 and RSS 2.0 modules may be used in Atom.

See Also

• The Atom Syndication Format