What Is Atom? | Professional XML (Programmer to Programmer)

As you saw in the discussion of the various semicompatible variants of RSS, it can be anything but Really Simple. Partly because of this complexity and partly because of the management of the RSS 2.0 specification, some developers decided to begin work on Atom. The idea was to take the best features of RSS and fix the parts that caused confusion during implementation.

The core structure of an Atom 1.0 feed consists of:

q The root node is feed, with a pointer to the Atom namespace (http://www.w3.org/2005/Atom).
q Channel information in the feed itself as child elements.
q One or more entry elements, containing the content.
q One curious feature of Atom is that the root node could also be a single entry. Although you probably won't encountered this often when processing an Atom feed, it does mean that entries can be isolated from the overall feed and still remain valid.

Listing 18-3 shows a simple Atom 1.0 feed.

Listing 18-3: A sample Atom 1.0 feed

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>      <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en-US">      <title type="html">AtomEnabled.org</title>      <subtitle type="html">Your one stop shop for all Atom API and syndication      information.</subtitle>      <link href="http://www.atomenabled.org/atom.xml" rel="self"/>      <link href="http://www.atomenabled.org" rel="alternate" title="AtomEnabled.org"      type="text/html"/>      <id>tag:blogger.com,1999:blog-6356614</id>      <updated>2005-09-15T13:33:06Z</updated>      <generator uri="http://www.blogger.com/" version="5.15">Blogger</generator>      <div  xmlns="http://www.w3.org/1999/xhtml">This is an Atom formatted      XML site feed. It is intended to be viewed in a Newsreader or syndicated to another      site. Please visit the <a      href="http://help.blogger.com/bin/answer.py?answer=697">Blogger Help</a> for more      info.</div>      <convertLineBreaks      xmlns="http://www.blogger.com/atom/ns#">false</convertLineBreaks>      <entry xmlns="http://www.w3.org/2005/Atom">      <author>      <name>Sam Ruby</name>      </author>      <published>2005-09-15T06:27:00-07:00</published>      <updated>2005-09-15T13:33:06Z</updated>      <link href="http://www.atomenabled.org/2005/09/atomenableds-atom-feed.php"      rel="alternate" title="AtomEnabled's Atom Feed" type="text/html"/>      <id>tag:blogger.com,1999:blog-6356614.post-112679118686717868</id>      <title type="html">AtomEnabled's Atom Feed</title>      <content type="xhtml" xml:base="http://www.atomenabled.org" xml:space="preserve">      <div xmlns="http://www.w3.org/1999/xhtml">This site's <a      href="http://www.atomenabled.org/atom.xml">Atom feed</a> has been converted to Atom      1.0. Addionally, the Feed Validator is <a      href="http://feedvalidator.org/news/archives/2005/09/15/atom_03_deprecated.html">no      w issuing deprecation warnings</a> whenever it encounters Atom 0.3 feeds.</div>      </content>      <draft xmlns="http://purl.org/atom-blog/ns#">false</draft>      </entry>      <entry xmlns="http://www.w3.org/2005/Atom">      <author>      <name>Sam Ruby</name>      </author>      <published>2005-07-31T13:08:00-07:00</published>      <updated>2005-08-01T02:37:13Z</updated>      <link href="http://www.atomenabled.org/2005/07/introduction-to-atom.php"      rel="alternate" title="Introduction to Atom" type="text/html"/>      <id>tag:blogger.com,1999:blog-6356614.post-112284122983872666</id>      <title type="html">Introduction to Atom</title>      <content type="xhtml" xml:base="http://www.atomenabled.org" xml:space="preserve">      <div xmlns="http://www.w3.org/1999/xhtml">An <a      href="http://www.atomenabled.org/developers/syndication/">introduction</a> to <a      href="http://www.atomenabled.org/developers/syndication/atom-format-spec.php">The      Atom Syndication Format</a> has been placed into the <a      href="http://www.atomenabled.org/developers/">Developers</a> > <a      href="http://www.atomenabled.org/developers/syndication/">Syndication</a> section      of this website.</div>      </content>      <draft xmlns="http://purl.org/atom-blog/ns#">false</draft>      </entry>      </feed>

Important points to note about this feed are:

q The root element of the document is feed.
q Use of namespaces to provide extensions.
q Content for each entry marked to identify the encoding type of the element (text, html, or xhtml).

The following table discusses the channel information elements.

Open table as spreadsheet

Element	Required/Optional	Notes
title	Required	A name for the feed. This is typically the same as the name for the site or application it comes from.
link	Optional (but highly recommended)	The URL of the feed. In addition to the URL itself, the link element should have the `rel=“self”` attribute to identify this URL as the one for the feed.
		In addition to this URL, the feed may have additional link elements pointing to related links with a `rel=“alternate”` attribute and the MIME type. For example, in addition to the link for the Atom feed, you may also include a link to the hosting Web site: <link rel="self" href="http://debar.com/foo/ feed.atom" /> <link rel="alternate" href="http://debar.com/foo" type="text/html" /> <link rel="license" href=" http://creativecommons .org/licenses/by/2.5/" type="application/rdf+xml"
id	Required	A unique identifier (URI) for the feed.
updated	Required	The date and time the feed was last changed. See Dates and Atom for details.
author	Required (see notes)	The creator of the feed. The author field, like most of the people-related elements in Atom, is in the form: <author> <name>Foo deBar</name> <uri>http://debar.com/blogs/foo</uri> <email>foo@debar.com</email> </author>
		Only name is required.
		The author element must either exist on every entry or in the feed. If you are certain there will be an author for every entry, you can treat it as optional here, and vice versa. It definitely doesn't hurt to have it in both places.
category	Optional	Multiple category elements can exist in Atom feeds. They are similar to the category elements in RSS. They provide information about the topic of the content. The structure of the category element is different from that in RSS, however. In Atom, a category has `term`, `scheme,` and `label` attributes: <category term="xml" scheme="scheme" label="XML" />
		`Term` is the only required attribute and represents the category or topic of the feed. `Scheme` is the organizing set of categories (or taxonomy). `Label` is a human-readable version of the term, if needed.
generator	Optional	The application generating the Atom feed. A place for generators to either brag about their accomplishments or provide the target for user-anger.
icon	Optional	A URL to a graphic for the feed. Generally, this would be an icon or other small graphic. It should generally be square.
logo	Optional	A URL to a graphic for the feed. This differs from `icon` in that it should be twice as wide as it is high.
rights	Optional	The rights conferred for the item, such as "copyright 2006 Foo deBar."
subtitle	Optional	An extra catchy phrase for the feed.

Dates and Atom

With all the variability possible when you process dates with RSS, it is almost refreshing to deal with dates in Atom. All dates must be in the RFC 3339 format (or the ISO 8601 or W3C date format if you'd rather look at those sites):

YYYY-MM-DDTHH:MM:SS-hh:mm (alternately the Z character can be used instead of a time zone)

For example, all the following are valid dates for Atom:

 2006-02-21T16:28:00-08:00 2006-01-01T12:00:00.00Z 2005-04-01T13:29:43.2&amp;plus;01:00

The Atom entry element can also be the root node in a document. If it is, the Atom namespace should be attached to the entry node. Most of the other entry features and child elements are similar to those in RSS. The following table covers the entry node elements used by Atom.

Open table as spreadsheet

Element	Required/Optional	Notes
title	Required	The title for the entry. The title should not contain markup, but should be plain text.
id	Required	A unique identifier for the entry. This may be a URI, but you should not assume that the URI is actually the URL for the item.
updated	Required	The date and time the entry was last updated (or created). See Dates and Atom for more details.
category	Optional	See the category description under the feed element 18-in a previous table. There can be multiple category elements per entry.
content	Optional	The content of the entry. In addition to the content itself, there should be a type attribute. The type attribute identifies the format of the content and should be one of the standard MIME types. Typically, `type=“text”`, `type=“html”` or `type=“xhtml”` are the most common type values.
		If the content element is empty, there should be a summary element (containing the content).
author	Required (see notes)	The person who created the entry. This element can be optional if the feed itself contains an author. However, in the interest of making parsing easier, it's probably a good idea to include the author element for each entry as well.
contributor	Optional	The person responsible for the entry. This differs from the author element in that there is only one author, but many people may have contributed information leading to the creation of the entry. Multiple contributor elements may exist per entry.
link	Optional	The URL of the entry, or the content pointed at by the entry. Multiple links per entry may exist, but they should differ by the type and/or hreflang. Each link should have the following attributes: `href=` The URL of the item (Required). `rel=` Optional attribute describing the relationship of the link to the content. One of self (the content is the entry itself), related (the link points to related information, such as company- specific information), alternate (the link points at another form of the entry, such as a PDF version), enclosure (the link points at a large file, such as audio or video), or via (the link points to the original source of the entry). `type=` Optional MIME type of the content referenced by the link. `hreflang=` Optional language of the content pointed at by the href. This enables you to have multiple translations pointed at by the same entry. `title=` Optional text to display for the link `length=` Optional length (in bytes) of the content referenced by the link.
published	Optional	Date and time the entry was created. See Dates and Atom for more details.
rights	Optional	Any copyright information associated with the entry.
source	Optional	Information about the original source of the Atom entry. Because a feed may actually contain entries created from multiple Atom feeds, this element can be used to provide information about the original feed for the entry.
summary	Optional	A short version of the content. This should have a type attribute (as described under content earlier). It should be different from the content (an excerpt or abstract) if present.