Home >> FAQs/Tutorials >> RSS Tutorials >> Index

RSS Tutorials - The Atom Syndication Format

By: M. Nottingham, Ed. & R. Sayre, Ed.

(Continued from previous topic...)

The Atom Syndication Format - Reference Document


Network Working Group                                 M. Nottingham, Ed.
Request for Comments: 4287                                 R. Sayre, Ed.
Category: Standards Track                                  December 2005


                      The Atom Syndication Format

Status of This Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2005).

Abstract

   This document specifies Atom, an XML-based Web content and metadata
   syndication format.

Table of Contents

   1. Introduction ....................................................3
      1.1. Examples ...................................................3
      1.2. Namespace and Version ......................................5
      1.3. Notational Conventions .....................................5
   2. Atom Documents ..................................................6
   3. Common Atom Constructs ..........................................7
      3.1. Text Constructs ............................................7
           3.1.1. The "type" Attribute ................................8
      3.2. Person Constructs .........................................10
           3.2.1. The "atom:name" Element ............................10
           3.2.2. The "atom:uri" Element .............................10
           3.2.3. The "atom:email" Element ...........................10
      3.3. Date Constructs ...........................................10
   4. Atom Element Definitions .......................................11
      4.1. Container Elements ........................................11
           4.1.1. The "atom:feed" Element ............................11
           4.1.2. The "atom:entry" Element ...........................13
           4.1.3. The "atom:content" Element .........................14
      4.2. Metadata Elements .........................................17
           4.2.1. The "atom:author" Element ..........................17
           4.2.2. The "atom:category" Element ........................18
           4.2.3. The "atom:contributor" Element .....................18

[Page 1]

           4.2.4. The "atom:generator" Element .......................18
           4.2.5. The "atom:icon" Element ............................19
           4.2.6. The "atom:id" Element ..............................19
           4.2.7. The "atom:link" Element ............................21
           4.2.8. The "atom:logo" Element ............................23
           4.2.9. The "atom:published" Element .......................23
           4.2.10. The "atom:rights" Element .........................24
           4.2.11. The "atom:source" Element .........................24
           4.2.12. The "atom:subtitle" Element .......................25
           4.2.13. The "atom:summary" Element ........................25
           4.2.14. The "atom:title" Element ..........................25
           4.2.15. The "atom:updated" Element ........................25
   5. Securing Atom Documents ........................................26
      5.1. Digital Signatures ........................................26
      5.2. Encryption ................................................27
      5.3. Signing and Encrypting ....................................28
   6. Extending Atom .................................................28
      6.1. Extensions from Non-Atom Vocabularies .....................28
      6.2. Extensions to the Atom Vocabulary .........................28
      6.3. Processing Foreign Markup .................................28
      6.4. Extension Elements ........................................29
           6.4.1. Simple Extension Elements ..........................29
           6.4.2. Structured Extension Elements ......................29
   7. IANA Considerations ............................................30
      7.1. Registry of Link Relations ................................31
   8. Security Considerations ........................................31
      8.1. HTML and XHTML Content ....................................31
      8.2. URIs ......................................................31
      8.3. IRIs ......................................................31
      8.4. Spoofing ..................................................31
      8.5. Encryption and Signing ....................................32
   9. References .....................................................32
      9.1. Normative References ......................................32
      9.2. Informative References ....................................34
   Appendix A. Contributors ..........................................35
   Appendix B. RELAX NG Compact Schema ...............................35

[Page 2]

1.  Introduction

   Atom is an XML-based document format that describes lists of related
   information known as "feeds".  Feeds are composed of a number of
   items, known as "entries", each with an extensible set of attached
   metadata.  For example, each entry has a title.

   The primary use case that Atom addresses is the syndication of Web
   content such as weblogs and news headlines to Web sites as well as
   directly to user agents.

1.1.  Examples

   A brief, single-entry Atom Feed Document:

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

[Page 3]

   A more extensive, single-entry Atom Feed Document:

   <?xml version="1.0" encoding="utf-8"?>
   <feed xmlns="http://www.w3.org/2005/Atom">
     <title type="text">dive into mark</title>
     <subtitle type="html">
       A &lt;em&gt;lot&lt;/em&gt; of effort
       went into making this effortless
     </subtitle>
     <updated>2005-07-31T12:29:29Z</updated>
     <id>tag:example.org,2003:3</id>
     <link rel="alternate" type="text/html"
      hreflang="en" href="http://example.org/"/>
     <link rel="self" type="application/atom+xml"
      href="http://example.org/feed.atom"/>
     <rights>Copyright (c) 2003, Mark Pilgrim</rights>
     <generator uri="http://www.example.com/" version="1.0">
       Example Toolkit
     </generator>
     <entry>
       <title>Atom draft-07 snapshot</title>
       <link rel="alternate" type="text/html"
        href="http://example.org/2005/04/02/atom"/>
       <link rel="enclosure" type="audio/mpeg" length="1337"
        href="http://example.org/audio/ph34r_my_podcast.mp3"/>
       <id>tag:example.org,2003:3.2397</id>
       <updated>2005-07-31T12:29:29Z</updated>
       <published>2003-12-13T08:29:29-04:00</published>
       <author>
         <name>Mark Pilgrim</name>
         <uri>http://example.org/</uri>
         <email>f8dy@example.com</email>
       </author>
       <contributor>
         <name>Sam Ruby</name>
       </contributor>
       <contributor>
         <name>Joe Gregorio</name>
       </contributor>
       <content type="xhtml" xml:lang="en"
        xml:base="http://diveintomark.org/">
         <div xmlns="http://www.w3.org/1999/xhtml">
           <p><i>[Update: The Atom draft is finished.]</i></p>
         </div>
       </content>
     </entry>
   </feed>

[Page 4]

1.2.  Namespace and Version

   The XML Namespaces URI [W3C.REC-xml-names-19990114] for the XML data
   format described in this specification is:

   http://www.w3.org/2005/Atom

   For convenience, this data format may be referred to as "Atom 1.0".
   This specification uses "Atom" internally.

1.3.  Notational Conventions

   This specification describes conformance in terms of two artifacts:
   Atom Feed Documents and Atom Entry Documents.  Additionally, it
   places some requirements on Atom Processors.

   This specification uses the namespace prefix "atom:" for the
   Namespace URI identified in Section 1.2, above.  Note that the choice
   of namespace prefix is arbitrary and not semantically significant.

   Atom is specified using terms from the XML Infoset
   [W3C.REC-xml-infoset-20040204].  However, this specification uses a
   shorthand for two common terms: the phrase "Information Item" is
   omitted when naming Element Information Items and Attribute
   Information Items.  Therefore, when this specification uses the term
   "element," it is referring to an Element Information Item in Infoset
   terms.  Likewise, when it uses the term "attribute," it is referring
   to an Attribute Information Item.

   Some sections of this specification are illustrated with fragments of
   a non-normative RELAX NG Compact schema [RELAX-NG].  However, the
   text of this specification provides the definition of conformance.  A
   complete schema appears in Appendix B.

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in BCP 14, [RFC2119], as
   scoped to those conformance targets.

[Page 5]

2.  Atom Documents

   This specification describes two kinds of Atom Documents: Atom Feed
   Documents and Atom Entry Documents.

   An Atom Feed Document is a representation of an Atom feed, including
   metadata about the feed, and some or all of the entries associated
   with it.  Its root is the atom:feed element.

   An Atom Entry Document represents exactly one Atom entry, outside of
   the context of an Atom feed.  Its root is the atom:entry element.

   namespace atom = "http://www.w3.org/2005/Atom"
   start = atomFeed | atomEntry

   Both kinds of Atom Documents are specified in terms of the XML
   Information Set, serialized as XML 1.0 [W3C.REC-xml-20040204] and
   identified with the "application/atom+xml" media type.  Atom
   Documents MUST be well-formed XML.  This specification does not
   define a DTD for Atom Documents, and hence does not require them to
   be valid (in the sense used by XML).

   Atom allows the use of IRIs [RFC3987].  Every URI [RFC3986] is also
   an IRI, so a URI may be used wherever below an IRI is named.  There
   are two special considerations: (1) when an IRI that is not also a
   URI is given for dereferencing, it MUST be mapped to a URI using the
   steps in Section 3.1 of [RFC3987] and (2) when an IRI is serving as
   an atom:id value, it MUST NOT be so mapped, so that the comparison
   works as described in Section 4.2.6.1.

   Any element defined by this specification MAY have an xml:base
   attribute [W3C.REC-xmlbase-20010627].  When xml:base is used in an
   Atom Document, it serves the function described in section 5.1.1 of
   [RFC3986], establishing the base URI (or IRI) for resolving any
   relative references found within the effective scope of the xml:base
   attribute.

   Any element defined by this specification MAY have an xml:lang
   attribute, whose content indicates the natural language for the
   element and its descendents.  The language context is only
   significant for elements and attributes declared to be "Language-
   Sensitive" by this specification.  Requirements regarding the content
   and interpretation of xml:lang are specified in XML 1.0
   [W3C.REC-xml-20040204], Section 2.12.

[Page 6]

   atomCommonAttributes =
      attribute xml:base { atomUri }?,
      attribute xml:lang { atomLanguageTag }?,
      undefinedAttribute*

   Atom is an extensible format.  See Section 6 of this document for a
   full description of how Atom Documents can be extended.

   Atom Processors MAY keep state sourced from Atom Feed Documents and
   combine them with other Atom Feed Documents, in order to facilitate a
   contiguous view of the contents of a feed.  The manner in which Atom
   Feed Documents are combined in order to reconstruct a feed (e.g.,
   updating entries and metadata, dealing with missing entries) is out
   of the scope of this specification.

3.  Common Atom Constructs

   Many of Atom's elements share a few common structures.  This section
   defines those structures and their requirements for convenient
   reference by the appropriate element definitions.

   When an element is identified as being a particular kind of
   construct, it inherits the corresponding requirements from that
   construct's definition in this section.

   Note that there MUST NOT be any white space in a Date construct or in
   any IRI.  Some XML-emitting implementations erroneously insert white
   space around values by default, and such implementations will emit
   invalid Atom Documents.

3.1.  Text Constructs

   A Text construct contains human-readable text, usually in small
   quantities.  The content of Text constructs is Language-Sensitive.

   atomPlainTextConstruct =
      atomCommonAttributes,
      attribute type { "text" | "html" }?,
      text

   atomXHTMLTextConstruct =
      atomCommonAttributes,
      attribute type { "xhtml" },
      xhtmlDiv

   atomTextConstruct = atomPlainTextConstruct | atomXHTMLTextConstruct

[Page 7]

3.1.1.  The "type" Attribute

   Text constructs MAY have a "type" attribute.  When present, the value
   MUST be one of "text", "html", or "xhtml".  If the "type" attribute
   is not provided, Atom Processors MUST behave as though it were
   present with a value of "text".  Unlike the atom:content element
   defined in Section 4.1.3, MIME media types [MIMEREG] MUST NOT be used
   as values for the "type" attribute on Text constructs.

3.1.1.1.  Text

   Example atom:title with text content:

   ...
   <title type="text">
     Less: &lt;
   </title>
   ...

   If the value is "text", the content of the Text construct MUST NOT
   contain child elements.  Such text is intended to be presented to
   humans in a readable fashion.  Thus, Atom Processors MAY collapse
   white space (including line breaks) and display the text using
   typographic techniques such as justification and proportional fonts.

3.1.1.2.  HTML

   Example atom:title with HTML content:

   ...
   <title type="html">
     Less: &lt;em> &amp;lt; &lt;/em>
   </title>
   ...

   If the value of "type" is "html", the content of the Text construct
   MUST NOT contain child elements and SHOULD be suitable for handling
   as HTML [HTML].  Any markup within MUST be escaped; for example,
   "<br>" as "&lt;br>".  HTML markup within SHOULD be such that it could
   validly appear directly within an HTML <DIV> element, after
   unescaping.  Atom Processors that display such content MAY use that
   markup to aid in its display.

[Page 8]

3.1.1.3.  XHTML

   Example atom:title with XHTML content:

   ...
   <title type="xhtml" xmlns:xhtml="http://www.w3.org/1999/xhtml">
     <xhtml:div>
       Less: <xhtml:em> &lt; </xhtml:em>
     </xhtml:div>
   </title>
   ...

   If the value of "type" is "xhtml", the content of the Text construct
   MUST be a single XHTML div element [XHTML] and SHOULD be suitable for
   handling as XHTML.  The XHTML div element itself MUST NOT be
   considered part of the content.  Atom Processors that display the
   content MAY use the markup to aid in displaying it.  The escaped
   versions of characters such as "&" and ">" represent those
   characters, not markup.


   Examples of valid XHTML content:

   ...
   <summary type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
         This is <b>XHTML</b> content.
      </div>
   </summary>
   ...
   <summary type="xhtml">
      <xhtml:div xmlns:xhtml="http://www.w3.org/1999/xhtml">
         This is <xhtml:b>XHTML</xhtml:b> content.
      </xhtml:div>
   </summary>
   ...

   The following example assumes that the XHTML namespace has been bound
   to the "xh" prefix earlier in the document:

   ...
   <summary type="xhtml">
      <xh:div>
         This is <xh:b>XHTML</xh:b> content.
      </xh:div>
   </summary>
   ...

[Page 9]

3.2.  Person Constructs

   A Person construct is an element that describes a person,
   corporation, or similar entity (hereafter, 'person').

   atomPersonConstruct =
      atomCommonAttributes,
      (element atom:name { text }
       & element atom:uri { atomUri }?
       & element atom:email { atomEmailAddress }?
       & extensionElement*)

   This specification assigns no significance to the order of appearance
   of the child elements in a Person construct.  Person constructs allow
   extension Metadata elements (see Section 6.4).

3.2.1.  The "atom:name" Element

   The "atom:name" element's content conveys a human-readable name for
   the person.  The content of atom:name is Language-Sensitive.  Person
   constructs MUST contain exactly one "atom:name" element.

3.2.2.  The "atom:uri" Element

   The "atom:uri" element's content conveys an IRI associated with the
   person.  Person constructs MAY contain an atom:uri element, but MUST
   NOT contain more than one.  The content of atom:uri in a Person
   construct MUST be an IRI reference [RFC3987].

3.2.3.  The "atom:email" Element

   The "atom:email" element's content conveys an e-mail address
   associated with the person.  Person constructs MAY contain an
   atom:email element, but MUST NOT contain more than one.  Its content
   MUST conform to the "addr-spec" production in [RFC2822].

3.3.  Date Constructs

   A Date construct is an element whose content MUST conform to the
   "date-time" production in [RFC3339].  In addition, an uppercase "T"
   character MUST be used to separate date and time, and an uppercase
   "Z" character MUST be present in the absence of a numeric time zone
   offset.

   atomDateConstruct =
      atomCommonAttributes,
      xsd:dateTime

[Page 10]

   Such date values happen to be compatible with the following
   specifications: [ISO.8601.1988], [W3C.NOTE-datetime-19980827], and
   [W3C.REC-xmlschema-2-20041028].

   Example Date constructs:

   <updated>2003-12-13T18:30:02Z</updated>
   <updated>2003-12-13T18:30:02.25Z</updated>
   <updated>2003-12-13T18:30:02+01:00</updated>
   <updated>2003-12-13T18:30:02.25+01:00</updated>

   Date values SHOULD be as accurate as possible.  For example, it would
   be generally inappropriate for a publishing system to apply the same
   timestamp to several entries that were published during the course of
   a single day.

4.  Atom Element Definitions

4.1.  Container Elements

4.1.1.  The "atom:feed" Element

   The "atom:feed" element is the document (i.e., top-level) element of
   an Atom Feed Document, acting as a container for metadata and data
   associated with the feed.  Its element children consist of metadata
   elements followed by zero or more atom:entry child elements.

   atomFeed =
      element atom:feed {
         atomCommonAttributes,
         (atomAuthor*
          & atomCategory*
          & atomContributor*
          & atomGenerator?
          & atomIcon?
          & atomId
          & atomLink*
          & atomLogo?
          & atomRights?
          & atomSubtitle?
          & atomTitle
          & atomUpdated
          & extensionElement*),
         atomEntry*
      }

   This specification assigns no significance to the order of atom:entry
   elements within the feed.

[Page 11]

   The following child elements are defined by this specification (note
   that the presence of some of these elements is required):

   o  atom:feed elements MUST contain one or more atom:author elements,
      unless all of the atom:feed element's child atom:entry elements
      contain at least one atom:author element.
   o  atom:feed elements MAY contain any number of atom:category
      elements.
   o  atom:feed elements MAY contain any number of atom:contributor
      elements.
   o  atom:feed elements MUST NOT contain more than one atom:generator
      element.
   o  atom:feed elements MUST NOT contain more than one atom:icon
      element.
   o  atom:feed elements MUST NOT contain more than one atom:logo
      element.
   o  atom:feed elements MUST contain exactly one atom:id element.
   o  atom:feed elements SHOULD contain one atom:link element with a rel
      attribute value of "self".  This is the preferred URI for
      retrieving Atom Feed Documents representing this Atom feed.
   o  atom:feed elements MUST NOT contain more than one atom:link
      element with a rel attribute value of "alternate" that has the
      same combination of type and hreflang attribute values.
   o  atom:feed elements MAY contain additional atom:link elements
      beyond those described above.
   o  atom:feed elements MUST NOT contain more than one atom:rights
      element.
   o  atom:feed elements MUST NOT contain more than one atom:subtitle
      element.
   o  atom:feed elements MUST contain exactly one atom:title element.
   o  atom:feed elements MUST contain exactly one atom:updated element.

   If multiple atom:entry elements with the same atom:id value appear in
   an Atom Feed Document, they represent the same entry.  Their
   atom:updated timestamps SHOULD be different.  If an Atom Feed
   Document contains multiple entries with the same atom:id, Atom
   Processors MAY choose to display all of them or some subset of them.
   One typical behavior would be to display only the entry with the
   latest atom:updated timestamp.

4.1.1.1.  Providing Textual Content

   Experience teaches that feeds that contain textual content are in
   general more useful than those that do not.  Some applications (one
   example is full-text indexers) require a minimum amount of text or
   (X)HTML to function reliably and predictably.  Feed producers should
   be aware of these issues.  It is advisable that each atom:entry
   element contain a non-empty atom:title element, a non-empty

[Page 12]

(Continued on next topic...)

  1. The Atom Syndication Format - Reference Document
  2. The Atom Syndication Format - Part 2
  3. The Atom Syndication Format - Part 3
  4. The Atom Syndication Format - Part 4

Selected Developer Jobs:

More...