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
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
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>
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 <em>lot</em> 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>
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.
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.
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
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: <
</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: <em> &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 "<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.
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> < </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>
...
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
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.
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
atom:content element when that element is present, and a non-empty
atom:summary element when the entry contains no atom:content element.
However, the absence of atom:summary is not an error, and Atom
Processors MUST NOT fail to function correctly as a consequence of
such an absence.
4.1.2. The "atom:entry" Element
The "atom:entry" element represents an individual entry, acting as a
container for metadata and data associated with the entry. This
element can appear as a child of the atom:feed element, or it can
appear as the document (i.e., top-level) element of a stand-alone
Atom Entry Document.
atomEntry =
element atom:entry {
atomCommonAttributes,
(atomAuthor*
& atomCategory*
& atomContent?
& atomContributor*
& atomId
& atomLink*
& atomPublished?
& atomRights?
& atomSource?
& atomSummary?
& atomTitle
& atomUpdated
& extensionElement*)
}
This specification assigns no significance to the order of appearance
of the child elements of atom:entry.
The following child elements are defined by this specification (note
that it requires the presence of some of these elements):
o atom:entry elements MUST contain one or more atom:author elements,
unless the atom:entry contains an atom:source element that
contains an atom:author element or, in an Atom Feed Document, the
atom:feed element contains an atom:author element itself.
o atom:entry elements MAY contain any number of atom:category
elements.
o atom:entry elements MUST NOT contain more than one atom:content
element.
o atom:entry elements MAY contain any number of atom:contributor
elements.
o atom:entry elements MUST contain exactly one atom:id element.
o atom:entry elements that contain no child atom:content element
MUST contain at least one atom:link element with a rel attribute
value of "alternate".
o atom:entry 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:entry elements MAY contain additional atom:link elements