AtomEnabled

Atom Syndication Format - Introduction

Contents

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:

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>

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

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

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>

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

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