APE (Atom/Pie/Echo) Working Group | M Nottingham |
December 2003 |
Abstract
This specification describes version 0.2 of the Atom, an XML-based Web content and metadata syndication format.
Editorial Notes
This draft is made available for historical purposes only; DO NOT implement it or ship products conforming to it. This work has migrated to the ATOMPUB Working Group in the IETF.
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.
Table of Contents
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
1 Introduction
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 ]]
1.1 Conformance
[[ talk about atom documents and atom consumers, and how requirements are placed on them ]]
1.2 Notational Conventions
[[ 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 ]]
2 Atom's Use of XML
[[ 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? ]]
3 Atom XML Constructs
3.1 The "atom:feed" Construct
3.1.1 "version" Attribute
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".
3.1.2 "xml:lang" Attribute
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?]].
3.1.3 "atom:title" Element
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.
3.1.4 "atom:link" Element
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
3.1.5 "atom:modified" 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?]].
3.1.6 "atom:author" Element
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.
3.1.7 "atom:tagline" 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.
3.1.8 "atom:id" Element
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.
3.1.9 "atom:generator" Element
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.
3.1.10 "atom:copyright" Element
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.
3.1.11 "atom:contributor" Element
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.
3.1.12 "atom:entry" 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.
3.2 The "atom:entry" Construct
3.2.1 "atom:title" 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.
3.2.2 "atom:link" Element
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
3.2.3 "atom:modified" 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?]].
3.2.4 "atom:author" Element
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]].
3.2.5 "atom:contributor" Element
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.
3.2.6 "atom:id" 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.
3.2.7 "atom:issued" Element
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.
3.2.8 "atom:created" Element
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.
3.2.9 "atom:summary" Element
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.
3.2.10 "atom:content" Element
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.
- A mode attribute with the value "xml" indicates that the element's content is inline xml (for example, namespace-qualified XHTML).
- A mode attribute with the value "escaped" indicates that the element's content is an escaped string. Consumers MUST unescape the element's content before processing it as the indicated media type.
- A mode attribute with the value "base64" indicates that the element's content is base64-encoded [[ref]]. Consumers MUST decode the element's content before processing it as the indicated media type.
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.
3.3 "atom:author" Element
The "atom:author" construct (hereafter, "author") conveys the identity of an author or creator of an entry and/or feed (depending on its context).
3.3.1 "atom:name" Element
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.
3.3.2 "atom:url" Element
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.
3.3.3 "atom:email" Element
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]].
3.4 "atom:contributor" Element
The "atom:contributor" construct conveys the identity of a contributor to the work. Its content model is identical to that of atom:author.
4 Managing Feed State
[[ talk about what it means to keep a view of a feed ]]
5 Embedding Atom Constructs in Other Formats
6 Extending Atom
7 IANA Considerations
[[ the media type registration ]]
8 Security Considerations
References
[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. |
Author's Address
Mark Nottingham | |
EMail: | mnot@pobox.com |
URI: | http://www.mnot.net/ |
A Contributors
The following people contributed to this specification: Tim Bray, Mark Pilgrim, and Sam Ruby.