APE (Atom/Pie/Echo): draft-nottingham-atom-format-02

This specification describes version 0.3 of the Atom, an XML-based Web content and metadata syndication format.

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; see RFC4287.

Sections called out like this indicate editorial notes that should be removed before final publication.

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, 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 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.

Details of comunication protocols between software agents using Atom are to be found in the Atom API specification.

A minimal, single-entry Atom feed serialized as XML 1.0:

<?xml version="1.0" encoding="utf-8"?>
<feed version="0.3" xmlns="http://purl.org/atom/ns#">
    <title>dive into mark</title>
    <link rel="alternate" type="text/html" href="http://diveintomark.org/"/>
    <modified>2003-12-13T18:30:02Z</modified>
    <author>
        <name>Mark Pilgrim</name>
    </author>
    <entry>
        <title>Atom 0.3 snapshot</title>
        <link rel="alternate" type="text/html" href="http://diveintomark.org/2003/12/13/atom03"/>
        <id>tag:diveintomark.org,2003:3.2397</id>
        <issued>2003-12-13T08:29:29-04:00</issued>
        <modified>2003-12-13T18:30:02Z</modified>
    </entry>
</feed>

talk about atom documents and atom consumers, and how requirements are placed on them

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.

This specification uses XML Namespaces (W3C.REC-xml-names-19990114) to uniquely identify XML elements and attribute names. It uses the following namespace prefixes for the indicated namespace URIs;

http://purl.org/atom/ns#

Note that the choice of any namespace prefix is arbitrary and not semantically significant.

Atom is specified using the XML Infoset [W3C.REC-xml-infoset-20011024], but uses a shorthand for common terms; the phrase "Information Item" is not used when naming XML constructs.

Therefore, when this specification uses the term "element," it is refering to an Element Information Item in Infoset terms. Likewise, when it uses the term "attribute," it is refering to an Attribute Information Item.

Furthermore, when it indicates that the content of an element or attribute is a "string," it is referring to a set of one or more Character Information Items.

children / contains

An Atom document is an XML document whose document element is the atom:feed element, as described below.

Atom is specified in terms of the XML Infoset, and therefore may be serialized in a variety of fashions. However, the canonical serialization of an Atom document is XML 1.0, and this is the only serialization that can be identified with the application/atom+xml media type.

Atom documents MAY have a Document Type Declaration.

Entities

Atom documents SHOULD NOT contain Processing Instructions, unless they are a commonly used convention outside the scope of Atom (e.g., the PI for XSLT processing).

Atom documents MAY contain Comments wherever they are legal in XML.

All elements and attributes in an Atom document MUST be namespace-qualified. Note that this requirement does not preclude the use of a default namespace.

Any element in an Atom document MAY have an xml:base attribute. However, XML Base [W3C.REC-xmlbase-20010627] processing MUST NOT be applied to element or attribute content, unless that element or attribute's specification explicitly includes XML Base processing.

Any element MAY have an xml:lang attribute whose content indicates the default natural language of the element's content. The content of this attribute element MUST be a registered language tag (RFC3066). When determining element content's natural language, the first xml:lang attribute encountered in that element's ancestors MUST be used.

extensibility

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

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

A Content construct is an element with arbitrary child content, whose properties are described by the following attributes:

Content constructs MAY have a type attribute, whose value indicates the media type of the content. When present, this attribute's value MUST be a registered media type (RFC2045). If not present, its value MUST be considered to be text/plain.

Content constructs MAY have a mode attribute, whose value indicates the method used to encode the content. When present, this attribute's value MUST be listed below. If not present, its value MUST be considered to be xml.

• xml: A mode attribute with the value xml indicates that the element's content is inline XML (for example, namespace-qualified XHTML).

• escaped: A mode attribute with the value escaped indicates that the element's content is an escaped string. Processors MUST unescape the element's content before considering it as content of the indicated media type.

• base64: A mode attribute with the value base64 indicates that the element's content is base64-encoded [RFC2045]. Processors MUST decode the element's content before considering it as content of the the indicated media type.

A Person construct is an element with the following children:

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. Person constructs 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. Person constructs MAY contain an atom:url element, but MUST NOT contain more than one. The content of atom:url in a Person construct MUST be a URI [RFC2396].

xml:base [W3C.REC-xmlbase-20010627] processing MUST be applied to the atom:url element.

The atom:email element's content conveys an e-mail address associated with the Person construct. Person constructs MAY contain an atom:email element, but MUST NOT contain more than one. Its content MUST be an e-mail address [RFC2822].

Ordering of the element children of Person constructs MUST NOT be considered significant.

A Date construct is an element whose child content is a W3C Date-Time string [W3C.NOTE-datetime-19980827].

A Link construct is an element that MUST NOT have any child content, and has the following attributes:

The rel attribute indicates the type of relationship that the link represents. Link constructs MUST have a rel attribute, whose value MUST be a string, and MUST be one of the values enumerated in the Atom API specification [draft-gregorio-09].

The type attribute indicates an advisory media type; it MAY be used as a hint to determine the type of the representation which should be returned when the URI in the href attribute is dereferenced. Note that the type attribute does not override the actual media type returned with the representation.

Link constructs MUST have a type attribute, whose value MUST be a registered media type [RFC2045].

The href attribute contains the link's URI. Link constructs MUST have a href attribute, whose value MUST be a URI [RFC2396].

xml:base [W3C.REC-xmlbase-20010627] processing MUST be applied to the atom:url element.

The title attribute conveys human-readable information about the link. Link constructs MAY have a title attribute, whose value MUST be a string.

The atom:feed element is the document (i.e., top-level) element of the format described by this specification. Its children are a (potentially partial) representation of the state of the feed.

The atom:feed element MAY contain any namespace-qualified [W3C.REC-xml-names-19990114] elements as children. Ordering of the element children of atom:feed element MUST NOT be considered significant.

The following attributes and child elements are defined by this specification (note that it requires the presence of some of these elements):

atom:feed elements 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.3.

atom:feed elements SHOULD have an xml:lang attribute whose content indicates the default natural language of the feed. The content of this attribute element MUST be a registered language tag [RFC3066].

The atom:title element is a Content construct that conveys a human-readable title for the feed. atom:feed elements MUST contain exactly one atom:title element. If the feed describes a Web resource, its content SHOULD be the same as that resource's title.

The atom:link element is a Link construct that 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.

atom:feed elements MUST contain at least one atom:link element with a rel attribute value of alternate.

atom:feed elements MUST NOT contain more than one atom:link element with a rel attribute value of alternate that has the same type attribute value.

atom:feed elements MAY contain additional atom:link elements beyond those described above.

The atom:author element is a Person construct that indicates the default author of the feed. atom:feed elements MUST contain exactly one atom:author element, UNLESS all of the atom:feed element's child atom:entry elements contain an atom:author element. atom:feed elements MUST NOT contain more than one atom:author element.

explain inheritence

The atom:contributor element is a Person construct that indicates a person or other entity who contributes to the feed. atom:feed elements MAY contain one or more atom:contributor elements.

The atom:tagline element is a Content construct that conveys a human-readable description or tagline for the feed. atom:feed elements MAY contain an atom:tagline element, but MUST NOT contain more than one.

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. atom:feed elements 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 indentifies the software agent used to generate the feed, for debugging and other purposes. atom:feed elements MAY contain an atom:generator element, but MUST NOT contain more than one.

The content of this element, when present, MUST be a string that is a human-readable name for the generating agent.

The atom:generator element MAY have a url attribute whose value MUST be a URI. When dereferenced, that URI SHOULD produce a representation that is relevant to that agent.

The atom:generator element MAY have a version attribute that indicates the version of the generating agent. When present, its value MUST be a string.

The atom:copyright element is Content construct that conveys a human-readable copyright statement for the feed. atom:feed elements MAY contain an atom:copyright element, but MUST NOT contain more than one.

The atom:copyright element SHOULD NOT be used to convey machine-readable licensing information.

The atom:info element is a Content construct that conveys a human-readable explanation of the feed format itself. atom:feed elements MAY contain an atom:info element, but MUST NOT contain more than one.

The atom:info element SHOULD NOT considered meaningful by processors; it is a convenience to publishers in certain situations.

The atom:modified element is a Date construct that indicates the time when the state of the feed was last modified, including any changes to entries therein. atom:feed elements MUST contain exactly one atom:modified element.

The content of an atom:modified element SHOULD have a time zone whose value MUST be UTC.

The atom:entry element's represents an individual entry that is contained by the feed. atom:feed elements MAY contain one or more atom:entry elements.

The atom:entry element MAY contain any namespace-qualified [W3C.REC-xml-names-19990114] elements as children. Ordering of the element children of atom:entry element MUST NOT be considered significant.

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

The atom:title element is a Content construct that conveys a human-readable title for the entry. atom:entry elements MUST have exactly one atom:title element. If an entry describes a Web resource, its content SHOULD be the same as that resource's title.

The atom:link element is a Link construct that conveys a URI associated with the entry. The nature of the relationship as well as the link itself is determined by the element's content.

atom:entry elements MUST contain at least one atom:link element with a rel attribute value of alternate.

atom:entry elements MUST NOT contain more than one atom:link element with a rel attribute value of alternate that has the same type attribute value.

atom:entry elements MAY contain additional atom:link elements beyond those described above.

The atom:author element is a Person construct that indicates the default author of the entry. atom:entry elements MUST contain exactly one atom:author element, UNLESS the atom:feed element containing them contains an atom:author element itself. atom:entry elements MUST NOT contain more than one atom:author element.

explain inheritence

The atom:contributor element is a Person construct that indicates a person or other entity who contributes to the entry. atom:entry elements MAY contain one or more atom:contributor elements.

The atom:id element's content conveys a permanent, globally unique identifier for the entry. It MUST NOT change over time, even if other representations of the entry (such as a web representation pointed to by the entry's atom:link element) are relocated. If the same entry is syndicated in two atom:feeds published by the same entity, the entry's atom:id MUST be the same in both feeds.

The atom:modified element is a Date construct that indicates the time that the entry was last modified. atom:entry elements MUST contain an atom:modified element, but MUST NOT contain more than one.

The content of an atom:modified element MUST have a time zone whose value SHOULD be UTC.

The atom:issued element is a Date construct that indicates the time that the entry was issued. atom:entry elements MUST contain an atom:issued element, but MUST NOT contain more than one.

The content of an atom:issued element MAY omit a time zone.

The atom:created element is a Date construct that indicates the time that the entry was created. atom:entry elements MAY contain an atom:created element, but MUST NOT contain more than one.

The content of an atom:created element MUST have a time zone whose value SHOULD be UTC.

If atom:created is not present, its content MUST considered to be the same as that of atom:modified.

The atom:summary element is a Content construct that conveys a short summary, abstract or excerpt of the entry. atom:entry elements MAY contain an atom:created element, but MUST NOT contain more than one.

The atom:content element is a Content construct that conveys the content of the entry. atom:entry elements MAY contain one or more atom:content elements.

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.

talk about what it means to keep a view of a feed

...

...

The Atom format, when serialized as XML 1.0, can be identified with the following media type:

Magic number(s):

As specified for "application/xml" in RFC3023, section 3.2.

File extension:

.atom

Fragment identifiers:

As specified for "application/xml" in RFC3023, section 5.

Base URI:

As specified in RFC3023, section 6.

Macintosh File Type code:

TEXT

Person and email address to contact for further information:

Mark Nottingham

Intended usage:

COMMON

Author/Change controller:

This specification's author(s). [\[update upon publication]]

this is required