[Cache version from http://www.mnot.net/drafts/draft-nottingham-atom-format-00.html; use this canonical source if possible.]
| APE (Atom/Pie/Echo) Working Group | M Nottingham |
| December 2003 |
This specification describes version 0.2 of the Atom, an XML-based Web content and metadata syndication format.
This draft HAS NOT been submitted for publication, and does not have any status; it should be referred to as a "pre-draft."
Discussion of this draft happens in two fora;
Comments and suggestions can be directed to the mailing list, whilst active development happens on the Wiki.
Sections called out [[like this]] indicate editorial notes that should be removed before publication.
1
Introduction
1.1
Conformance
1.2
Notational Conventions
2
Atom's Use of XML
3
Atom XML Constructs
3.1
The "atom:feed" Construct
3.1.1
"version" Attribute
3.1.2
"xml:lang" Attribute
3.1.3
"atom:title" Element
3.1.4
"atom:link" Element
3.1.5
"atom:modified" Element
3.1.6
"atom:author" Element
3.1.7
"atom:tagline" Element
3.1.8
"atom:id" Element
3.1.9
"atom:generator" Element
3.1.10
"atom:copyright" Element
3.1.11
"atom:contributor" Element
3.1.12
"atom:entry" Element
3.2
The "atom:entry" Construct
3.2.1
"atom:title" Element
3.2.2
"atom:link" Element
3.2.3
"atom:modified" Element
3.2.4
"atom:author" Element
3.2.5
"atom:contributor" Element
3.2.6
"atom:id" Element
3.2.7
"atom:issued" Element
3.2.8
"atom:created" Element
3.2.9
"atom:summary" Element
3.2.10
"atom:content" Element
3.3
"atom:author" Element
3.3.1
"atom:name" Element
3.3.2
"atom:url" Element
3.3.3
"atom:email" Element
3.4
"atom:contributor" Element
4
Managing Feed State
5
Embedding Atom Constructs in Other Formats
6
Extending Atom
7
IANA Considerations
8
Security Considerations
§
References
§
Author's Address
A
Contributors
B
Revision History
§
Full Copyright Statement
Atom is an XML-based file format intended to allow lists of information, known as "feeds", to be synchronised between publishers and consumers. Feeds are composed of a number of items, each with an extensible set of attached metadata. For example, items each have a title.
The primary use case that Atom addresses is for syndicating Web content such as Weblogs and news headlines to other Web sites and directly to consumers. However, nothing precludes it from being used for other purposes and types of content.
[[ more motivation / design principles here ]]
[[ talk about atom documents and atom consumers, and how requirements are placed on them ]]
[[ declare namespace prefixes ]]
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 [RFC2119].
[[ define conformance targets: - CONSUMER - DOCUMENT - CONSTRUCT - EXTENSION ]]
[[ talk about namespaces, parsing requirements, etc. - RFC 3023 - use of XML in IETF RFC (forget the number) - xml:base not defined for atom items - xml:lang on any element; determining precedence - namespace: http://purl.org/atom/ns# - ordering significance - mixed content - what does 'contains' mean? - what does "string" mean? ]]
Feeds MUST have a "version" attribute whose content indicates the version of the Atom specification that the construct conforms to.
The version identifier for this specification is "0.2".
Feeds SHOULD have an "xml:lang" attribute whose content indicates the default natural language of the feed. The content of xml:lang in a feed construct MUST be [[...ref?]].
The "atom:title" element's content conveys a human-readable title for the feed. Feeds MUST contain exactly one "atom:title" element. If the feed describes a Web resource, it SHOULD be the same as that resource. The content of atom:title in a feed MUST be a string.
The "atom:link" element's content conveys a URI associated with the feed. The nature of the relationship as well as the link itself is determined by the element's content, whose model is identical to that of the HTML LINK element
The "atom:modified" element's content indicates the time that the feed was last modified, including any changes to entries therein. Feeds MUST contain exactly one atom:modified element whose content is a W3C Date-Time string [[ref]]. The date SHOULD be expressed in the "UTC" time zone [[reword?]].
The "atom:author" element's content indicates the default author of the feed. Feeds MUST contain exactly one atom:author element, UNLESS each of the feed's entries contains an atom:author element. Feeds MUST NOT contain more than one "atom:author" element.
See below for the content model of this element.
The "atom:tagline" element's content conveys a human-readable description or taglone for the feed. Feeds MAY contain an atom:tagline element, but MUST NOT contain more than one. The content of this element, when present, MUST be a string.
The "atom:id" element's content conveys a permanent, globally unique identifier for the feed. It MUST NOT change over time, even if the feed is relocated. Feeds MAY contain an atom:id element, but MUST NOT contain more than one. The content of this element, when present, MUST be a URI.
The "atom:generator" element's content indicates the software agent used to generate the feed, for debugging and other purposes. Feeds MAY contain an atom:generator element, but MUST NOT contain more than one. The content of this element, when present, MUST be a URI, and when dereferenced SHOULD produce a representation that is relevant to that agent.
The atom:generator element MAY contain an attribute, "name" that conveys a human-readable name for the generating agent. If present, this attribute MUST be a string.
The "atom:copyright" element's content conveys a human-readable copyright statement for the feed. Feeds MAY contain an atom:copyright element, but MUST NOT contain more than one. The content of this element, when present, MUST be a string.
This element SHOULD NOT be used to convey machine-readable licensing information.
The "atom:contributor" element's content indicates a person or other entity who contributes to the feed. Feeds MAY contain one or more atom:contributor elements. See below for the content model of this element.
The "atom:entry" element's content conveys an individual entry that is contained by the feed. Feeds MAY contain one or more atom:entry elements. See below for the content model of this element.
The "atom:title" element's content conveys a human-readable title for the entry. Entries MUST have exactly one "atom:title" element. If the entry describes a Web resource, it SHOULD be the same as that resource. The content of atom:title in an entry MUST be a string.
The "atom:link" element's content conveys a URI associated with the feed. The nature of the relationship as well as the link itself is determined by the element's content, whose model is identical to that of the HTML LINK element
The "atom:modified" element's content indicates the time that the entry was last modified. Entries MAY contain an atom:modified element, but MUST NOT contain more than one. When present, this element's content MUST be a W3C Date-Time string [[ref]]. The date SHOULD be expressed in the "UTC" time zone [[reword?]].
The "atom:author" element's content indicates the default author of the entry. Entries MUST contain exactly one atom:author element, UNLESS the feed containing them contains an atom:author element itself. Entries MUST NOT contain more than one "atom:author" element.
See below for the content model of this element [[ref]].
The "atom:contributor" element's content indicates a person or other entity who contributes to the entry. Entries MAY contain one or more atom:contributor elements. See below for the content model of this element.
The "atom:id" element's content conveys a permanent, globally unique identifier for the entry. It MUST NOT change over time, even if the entry is relocated. Entries MUST contain exactly one atom:id element whose content MUST be a URI.
The "atom:issued" element's content indicates the time that the entry was issued. Entries MUST contain exactly one atom:issued element, whose content MUST be a W3C Date-Time string [[ref]]. The date SHOULD include a timezone, and that timezone SHOULD be the publisher's timezone.
The "atom:created" element's content indicates the time that the entry was created. Entries MAY contain an atom:created element, but MUST NOT contain more than one. When this element is present, its content MUST be a W3C Date-Time string [[ref]]. The date SHOULD be expressed in the "UTC" time zone [[reword?]].
If atom:created is not present, CONSUMERS MUST consider its value to be the same as that of atom:modified.
The "atom:summary" element's content conveys a short summary, description or excerpt of the entry. Entries MAY contain an atom:created element, but MUST NOT contain more than one. When this element is present, its content MUST be a string.
The "atom:content" element's content conveys the content of the entry. Entries MAY contain one or more atom:content elements.
This element, when present, MUST have the "type" attribute, whose content indicates the media type of the content. The type attribute's value MUST be a media type [[ref]].
This element, when present, MAY have a "mode" attribute, whose value indicates the method used to encode the content.
If @type="multipart/alternative", @mode MUST NOT be specified, and content element MUST contain 1 or more content elements. These content elements MUST NOT specify @type="multipart/alternative" (i.e. only one level of nesting is allowed). Consumers SHOULD look at all alternative content elements and determine which one is most suitable, based on which @type and @mode the consumer supports, and preferences specified by the end user (if any). Consumers SHOULD NOT render more than one content alternative.
The "atom:author" construct (hereafter, "author") conveys the identity of an author or creator of an entry and/or feed (depending on its context).
The "atom:name" element's content conveys a human-readable name for the author. It MAY be the name of a corporation or other entity no individual authors can be named. Authors MUST contain exactly one "atom:name" element, whose content MUST be a string.
The "atom:url" element's content conveys a URI associated with the author. Authors MAY contain an atom:url element, but MUST NOT contain more than one. The content of atom:url in a author MUST be a URI.
the "atom:email" element's content conveys an e-mail address associated with the author. Authors MAY contain an atom:email element, but MUST NOT contain more than one. The content of atom:email in an author MUST be an e-mail addres [[ref]].
The "atom:contributor" construct conveys the identity of a contributor to the work. Its content model is identical to that of atom:author.
[[ talk about what it means to keep a view of a feed ]]
[[ the media type registration ]]
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC2396] | Berners-Lee, T., Fielding, R.T. and Masinter, L., "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. |
| Mark Nottingham | |
| EMail: | mnot@pobox.com |
| URI: | http://www.mnot.net/ |
The following people contributed to this specification: Tim Bray, Mark Pilgrim, and Sam Ruby.