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>

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.

Element Description
id Identifies the feed using a universally unique and permanent URI. If you have a long-term, renewable lease on your Internet domain name, then you can feel free to use your website's address. 
<id>http://example.com/</id>
title Contains a human readable title for the feed. Often the same as the title of the associated website. This value should not be blank. 
<title>Example, Inc.</title>
updated Indicates the last time the feed was modified in a significant way. 
<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:
Element Description
author Names one author of the feed. A feed may have multiple author elements. A feed must contain at least one author element unless all of the entry elements contain at least one author element. More info here. 
<author>
  <name>John Doe</name>
  <email>JohnDoe@example.com</email>
  <uri>http://example.com/~johndoe</uri>
</author>
link Identifies a related Web page. The type of relation is defined by the rel attribute. A feed is limited to one alternate per type and hreflang. A feed should contain a link back to the feed itself. More info here. 
<link rel="self" href="/feed" />

Optional feed elements

Here's a list of optional feed elements.

Element Description
category Specifies a category that the feed belongs to. A feed may have multiple category elements. More info here. 
<category term="sports"/>
contributor Names one contributor to the feed. An feed may have multiple contributor elements. More info here. 
<contributor>
  <name>Jane Doe</name>
</contributor>
generator Identifies the software used to generate the feed, for debugging and other purposes. Both the uri and version attributes are optional. 
<generator uri="/myblog.php" version="1.0">
  Example Toolkit
</generator>
icon Identifies a small image which provides iconic visual identification for the feed. Icons should be square. 
<icon>/icon.jpg</icon>
logo Identifies a larger image which provides visual identification for the feed. Images should be twice as wide as they are tall. 
<logo>/logo.jpg</logo>
rights Conveys information about rights, e.g. copyrights, held in and over the feed. More info here. 
<rights> © 2005 John Doe </rights>
subtitle Contains a human-readable description or subtitle for the feed. More info here. 
<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.

Element Description
id Identifies the entry using a universally unique and permanent URI. Suggestions on how to make a good id can be found here. Two entries in a feed can have the same value for id if they represent the same entry at different points in time. 
<id>http://example.com/blog/1234</id>
title Contains a human readable title for the entry. This value should not be blank. 
<title>Atom-Powered Robots Run Amok</title>
updated Indicates the last time the entry was modified in a significant way. This value need not change after a typo is fixed, only after a substantial modification. Generally, different entries in a feed will have different updated timestamps. 
<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:
Element Description
author Names one author of the entry. An entry may have multiple authors. An entry must contain at least one author element unless there is an author element in the enclosing feed, or there is an author element in the enclosed source element. More info here. 
<author>
  <name>John Doe</name>
</author>
content Contains or links to the complete content of the entry. Content must be provided if there is no alternate link, and should be provided if there is no summary. More info here. 
<content>complete story here</content>
link Identifies a related Web page. The type of relation is defined by the rel attribute. An entry is limited to one alternate per type and hreflang. An entry must contain an alternate link if there is no content element. More info here. 
<link rel="alternate" href="/blog/1234"/>
summary Conveys a short summary, abstract, or excerpt of the entry. Summary should be provided if there either is no content provided for the entry, or that content is not inline (i.e., contains a src attribute), or if the content is encoded in base64. More info here. 
<summary>Some text.</summary>

Optional elements of <entry>

Here's a list of optional feed elements.

Element Description
category Specifies a category that the entry belongs to. A entry may have multiple category elements. More info here. 
<category term="technology"/>
contributor Names one contributor to the entry. An entry may have multiple contributor elements. More info here. 
<contributor>
  <name>Jane Doe</name>
</contributor>
published Contains the time of the initial creation or first availability of the entry. 
<published>2003-12-13T09:17:51-08:00</published>
rights Conveys information about rights, e.g. copyrights, held in and over the entry. More info here. 
<rights type="html">
  &amp;copy; 2005 John Doe
</rights>
source Contains metadata from the source feed if this entry is a copy. 
<source>
  <id>http://example.org/</id>
  <title>Example, Inc.</title>
  <updated>2003-12-13T18:30:02Z</updated>
</source>

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> 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 &amp;lt;b&amp;gt;by SBC&amp;lt;/b&amp;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

Home · About · News · Docs · Terms