Atom feeds specification

The format for Atom feeds is specified in RFC 4287.

Structure

An Atom feed is an XML document with a single feed element as the root.

The items in the feed are represented with /feed/entry elements. These come after the metadata children. The order of the entry elements doesn’t matter.

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>...</id>
  <title type="text">...</title>
  <link rel="self" type="application/atom+xml"
    href="http://example.com/feed.atom"/>
  <link rel="alternate" type="text/html" hreflang="en"
    href="http://example.com/"/>
  <!--snip-->
  <entry>...</entry>
  <entry>...</entry>
</feed>

Feed

Typical metadata provided as children of feed:

• /feed/author [1..*] – see Author below
  • May only be omitted if all entry elements have an entry/author.
• /feed/id [1] – permanent, universally unique URI
  • May not be a relative reference.
• /feed/link with attribute rel="self" [0..1]
  • the preferred URI for retrieving this feed; recommended.
• /feed/title [1]
  • If the title is not plain text, set the type attr to html, and escape the HTML markup.
• /feed/updated [1]
  • A date-time construct, incl. final “Z” or time zone offset, e.g. “2003-12-13T18:30:02Z”, “2003-12-13T18:30:02+01:00”.

Optional:

• /feed/category [0..*] – see Category below
• /feed/contributor [0..*]
  • same format as author
• /feed/generator [0..1] – program used to generate the feed
  • May have uri and version attrs.
• /feed/icon [0..1] – URI
  • Should have an aspect ratio of 1:1.
• /feed/logo [0..1] – URI
  • Should have an aspect ratio of 2:1 (wide).
• /feed/link with attribute rel="alternate"
  • at most 1 per (type × hreflang) combination
• /feed/rights [0..1]
• /feed/subtitle [0..1]

Entry

Typical metadata provided as children of entry:

• /feed/entry/title [1]
• /feed/entry/id [1] – permanent, universally unique URI
  • May not be a relative reference.
  • Multiple entries with the same id are considered the same entry, but it is up to the application what it does with the different versions.
  • Keep the same ID when publishing a new revision (even in a different feed).
• /feed/entry/link [0..1] with attribute rel="alternate"
  • Required if content is not provided.
• /feed/entry/updated [1] – timestamp of most recent update
  • Same format as /feed/updated
• /feed/entry/summary [0..1]
  • May have type="xhtml", in which case, see /feed/entry/content below.
  • May be absent if a content element of type “xhtml” is provided.

Optional:

• /feed/entry/link [0..*] with attributes rel="alternate" and hreflang for translations
  • at most 1 per (type × hreflang) combination
• /feed/entry/link [0..*] with attributes rel="enclosure" type="audio/mpeg"
  • Preferably also set the length attr.
• /feed/entry/published [0..1] – timestamp of initial publication
  • Same format as /feed/updated
• /feed/entry/rights [0..1]
• /feed/entry/source [0..1] – if the entry was copied from a different feed
  • Use the metadata for the original feed and/or entry as children.
• /feed/entry/author [0..*] – see Author below
  • May only be omitted if /feed/author is provided.
• /feed/entry/contributor [0..*]
  • same format as author
• /feed/entry/category [0..*] – see Category below
• /feed/entry/content [0..1] with attr type="xhtml"
  • Its child must be a single <div xmlns="http://www.w3.org/1999/xhtml">.
  • Set the xml:base="https://..." attr on content for resolving relative links.
  • Set the xml:lang="en" attr on content.
  • The xml:base and xml:lang attributes could also be set on the feed element to reduce duplication.
  • Plain text or other media types are allowed instead of type="xhtml".
  • Alternatively, leave the content empty and set its src attr and set the type attr to the appropriate mimetype.

<entry>
  <title>...</title>
  <link rel="alternate" type="text/html"
    href="http://example.org/..."/>
  <id>...</id>
  <updated>2005-07-31T12:29:29Z</updated>
  <content type="xhtml"
    xml:base="http://example.com/"
    xml:lang="en">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>...</p>
    </div>
  </content>
</entry>

Author

The author element can be used in feed or entry. It has the following children:

• author/name [1]
• author/uri [0..1]
• author/email [0..1]

Category

The category element can be used in feed or entry. It has the following children:

• category/term [1]
• category/scheme [0..1]
• category/label [0..1]

References

• RFC 4287: The Atom Syndication Format