Abstract
Change definition of atom:feed to be recursive and eliminate the atom:head element, thus allowing multiple feeds per feed document with metadata being applied hierarchically.
Status
New proposal.
Rationale
Making a feed document strictly hierarchical and recursive solves a number of problems that have been previously attacked in a piecemeal fashion:
-
XML containment relates feed and entry metadata to the data being described, thereby defining a consistent model for future extension elements;
-
Multiple feeds can be aggregated and presented using a single data format without having to modify the entries within those feeds to incorporate their original feed metadata;
-
Digital signatures can be safely applied to feeds and entries without needing special-case exceptions on how to recreate the signature after aggregation;
-
Simplifies description of the Atom syndication format to containers (feed, entry, content) and metadata that targets its own parent (feed or entry).
Example
<?xml version="1.0" encoding="UTF-8"?>
<feed version="draft-ietf-atompub-format-06: do not deploy"
xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-06">
<title>Some Chapters of Books I Like</title>
<link href="http://example.org/"/>
<updated>2003-12-13T18:30:02Z</updated>
<author>
<name>John Doe</name>
</author>
<entry>
<title>Atom-Powered Robots Run Amok, Chapter One</title>
<link href="http://example.org/2003/12/13/atom03"/>
<id>vemmi://example.org/2003/32397</id>
<summary>It seemed like a good idea at first...</summary>
<updated>2003-12-13T18:30:02Z</updated>
</entry>
<feed>
<title>The Baron in the Trees</title>
<link href="http://example.org/"/>
<updated>2003-12-13T18:30:02Z</updated>
<author>
<name>Italo Calvino</name>
</author>
<contributor>
<name>Archibald Colquhoun</name>
</contributor>
<entry>
<title>Chapter One</title>
<link href="http://example.com/something"/>
<id>vemmi://example.org/2004/foo97</id>
<summary type="XHTML"><div xmlns="http://www.w3.org/1999/xhtml">
<i>It was on the fifteenth of June, 1767</i>, that Cosimo Piovasco di Rondò,
my brother, sat among us for the last time.</div></summary>
<updated>2004-12-13T18:30:02Z</updated>
</entry>
</feed>
</feed>
The current method:
<?xml version="1.0" encoding="UTF-8"?>
<feed version="draft-ietf-atompub-format-05: do not deploy"
xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-05">
<head>
<title>Some Chapters of Books I Like</title>
<link href="http://example.org/"/>
<updated>2003-12-13T18:30:02Z</updated>
<author>
<name>John Doe</name>
</author>
</head>
<entry>
<title>Atom-Powered Robots Run Amok, Chapter One</title>
<link href="http://example.org/2003/12/13/atom03"/>
<id>vemmi://example.org/2003/32397</id>
<summary>It seemed like a good idea at first...</summary>
<updated>2003-12-13T18:30:02Z</updated>
</entry>
<entry>
<head>
<title>The Baron in the Trees</title>
<link href="http://example.org/"/>
<updated>2003-12-13T18:30:02Z</updated>
<author>
<name>Italo Calvino</name>
</author>
<contributor>
<name>Archibald Colquhoun</name>
</contributor>
</head>
<title>Chapter One</title>
<link href="http://example.com/something"/>
<id>vemmi://example.org/2004/foo97</id>
<summary type="XHTML"><div xmlns="http://www.w3.org/1999/xhtml">
<i>It was on the fifteenth of June, 1767</i>, that Cosimo Piovasco di Rondò,
my brother, sat among us for the last time.</div></summary>
<updated>2004-12-13T18:30:02Z</updated>
</entry>
</feed>
Proposal
This will take some time to write ... RoyFielding
Change feed to contain (metadata, (feed* | entry*)).
Change entry to contain (metadata, content).
Declare everything else to be metadata, whether standard (atom namespace) or future extensions (other namespaces).
Only the outermost atom:feed or atom:entry would contain the atom version attribute, requiring that lower-level feeds be upgraded if necessary during encapsulation.
(sketching this in... RobertSayre)
in section 2:
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 feeds and entries associated
with it. Its document element is atom:feed.
An Atom Entry Document represents exactly one Atom Entry, outside of
the context of an Atom Feed. Its document element is atom:entry.
namespace atom =
"http://purl.org/atom/ns#draft-ietf-atompub-format-05"
start = atomFeed | atomEntry
Both kinds of Atom documents are specified in terms of the XML
Information Set, serialised as XML 1.0 [W3C.REC-xml-20040204] and
identified with the "application/atom+xml" media type. Atom
Documents MUST be well-formed XML.
Atom constrains the appearance and content of elements and
attributes; unless otherwise stated, Atom Documents MAY contain other
Information Items as appropriate. In particular, Comment Information
Items and Processing Instruction Information Items SHOULD be ignored
in the normal processing of an Atom Document.
[[ discussion of URI escaping and i18n, IRI ]]
[[ discussion of white space ]]
2.1 Metadata and Content
Atom documents consist of "container" and "metadata" elements.
All elements are properties of the container element which encloses them.
[[ RNC stuff ...]]
2.2 Extending Atom
Atom is extensible. All extension elements are considered to be
"metadata" elements. See the section titled 'Extending Atom' later in
this document for a full description of how Atom Documents can be
extended.
2.4 Common Attributes
Any element in an Atom Document MAY have an xml:base attribute. XML
Base [W3C.REC-xmlbase-20010627] processing MUST be applied to any
relative reference [RFC3986] present in an Atom Document. This
includes such elements and attributes as specified by Atom itself, as
well as those specified by extensions to Atom.
Any element in an Atom Document MAY have an xml:lang attribute, whose
content indicates the natural language of the element's content.
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 }?
In section 4:
4.1 Container Elements
Container elements are used to group metadata and content.
4.1.1 The "version" Attribute
The document element of an Atom document MUST have a "version"
attribute whose content indicates the version of the Atom
specification that the document conforms to. The content of this
attribute is unstructured text.
The version identifier for this specification is
"draft-ietf-atompub-format-05: do not deploy".
atomVersionAttribute =
attribute version {"draft-ietf-atompub-format-05 : do not deploy"}
The "version" attribute MUST NOT appear anywhere else in an Atom
document.
4.1.2 The "atom:feed" Element
The "atom:feed" element acts as a container for metadata and data
associated with the feed.
atomFeed =
element atom:feed {
atomCommonAttributes,
atomVersionAttribute?,
(atomEntry*
& atomFeed*
& atomTitle
& atomUpdated
& atomLink+
& atomId?
& atomAuthor?
& atomContributor*
& atomTagline?
& atomGenerator?
& atomInfo?
& atomCopyright?
& atomCategory*
& atomIntrospection?
& atomPost?
& anyElement*)
}
The following child elements are defined by this specification (note
that the presence of some of these elements is required):
o atom:feed elements MAY contain any number of atom:entry
elements.
o atom:feed elements MAY contain any number of atom:feed
elements.
o atom:feed elements MUST contain exactly one atom:title element.
o atom:feed elements MUST contain at least one atom:link element
with a rel attribute value of "alternate".
o 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. If a feed's atom:link element with
type="alternate" resolves to an HTML document, then that document
SHOULD have a autodiscovery link element [Atom-autodiscovery] that
reflects back to the feed. atom:head elements MAY contain
additional atom:link elements beyond those described above.
o 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:head elements MUST NOT
contain more than one atom:author element. [[inheritance]]
o atom:feed elements MUST NOT contain more than one
atom:contributor element.
o atom:feed elements MUST NOT contain more than one
atom:copyright element.
o atom:feed elements MUST NOT contain more than one atom:id
element.
o atom:feed elements MUST contain exactly one atom:updated element.
o atom:feed elements MAY contain any number of atom:category
elements.
o atom:feed elements MUST NOT contain more than one atom:post
element.
4.1.3 The "atom:entry" Element
The "atom:entry" element represents an individual 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 standalone Atom
Entry Document.
When appearing in an Atom Entry Document, atom:entry elements MUST
have a "version" attribute whose content indicates the version of the
Atom specification that the entry conforms to.
The version identifier for this specification is
"draft-ietf-atompub-format-05: do not deploy".
The atom:entry element MAY contain any namespace-qualified
[W3C.REC-xml-names-19990114] elements as children. This
specification assigns no significance to the order of appearance of
the child elements of atom:entry.
atomEntry =
element atom:entry {
atomCommonAttributes,
atomVersionAttribute?,
(atomTitle
& atomId
& atomLink*
& atomUpdated
& atomPublished?
& atomAuthor?
& atomContributor*
& atomHost?
& atomCopyright?
& atomCategory*
& atomEdit?
& atomSummary?
& atomContent?
& anyElement*)
}
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 have exactly one "atom:title" element.
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". 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.
o atom:entry elements MUST contain exactly one atom:updated element.
o atom:entry elements MUST NOT contain more than one atom:published
element.
o atom:entry elements MUST contain exactly one atom:author element,
unless, in an Atom Feed Document, the atom:head element contains
an atom:author element itself. atom:entry elements MUST NOT
contain more than one atom:author element.
o atom:entry elements MUST NOT contain more than one
atom:contributor element.
o atom:entry elements MUST NOT contain more than one atom:host
element.
o atom:entry elements MUST NOT contain more than one atom:copyright
element.
o atom:entry elements MAY contain any number of atom:category
elements.
o atom:entry elements MUST contain an atom:summary element in any of
the following cases:
* the atom:entry element contains no atom:content element.
* the atom:entry contains an atom:content which has a "src"
attribute (and is thus empty).
* the atom:entry contains content which is encoded in Base64;
i.e. the "type" attribute of atom:content is a MIME media type
[RFC2045] and does not begin with "text/" nor end with "+xml".
o atom:entry elements MUST NOT contain more than one atom:summary
element.
o atom:entry elements MUST NOT contain more than one atom:edit
element.
o atom:entry elements MUST NOT contain more than one atom:content
element.
4.1.4 The "atom:content" Element
The "atom:content" element either contains or links to the content of
an entry.
atomInlineTextContent =
element atom:content {
atomCommonAttributes,
attribute type { "TEXT" | "HTML" | atomMediaType }?,
(text)*
}
atomInlineXHTMLContent =
element atom:content {
atomCommonAttributes,
attribute type { "XHTML" | atomMediaType }?,
(text|anyElement)*
}
atomOutOfLineContent =
element atom:content {
atomCommonAttributes,
attribute type { "TEXT" | "HTML" | "XHTML" | atomMediaType }?,
attribute src { atomUri },
empty
}
atomContent = atomInlineTextContent
| atomInlineXHTMLContent
| atomOutOfLineContent
4.1.4.1 The "type" attribute
atom:content MAY have a "type" attribute, When present, the value MAY
be one of "TEXT", "HTML", or "XHTML". Failing that, it MUST be a
MIME media type [RFC2045] in which, to use the terminology of Section
5 of [RFC2045], the top level is a discrete type. If the type
attribute is not provided, software MUST behave as though it were
present with a value of "TEXT".
4.1.4.2 The "src" attribute
atom:content MAY have a "src" attribute, whose value MUST be a URI
reference [RFC3986]. If the "src" attribute is present, software MAY
use the URI to retrieve the content. If the "src" attribute is
present, atom:content MUST be empty. That is to say, the content may
be retrievable using "src=" URI, or it may be contained within
atom:content, but not both.
If the "src" attribute is present, the "type" attribute SHOULD be
provided and MUST be a MIME media type [RFC2045], rather than "TEXT",
"HTML", or "XHTML". The value is advisory; that is to say, upon
dereferencing the URI to retrieve the content, if the server
providing that content also provides a media type, the
server-provided media type is authoritative.
If the value of type begins with "text/" or ends with "+xml", the
content SHOULD be local; that is to say, no "src" attribute should be
provided.
4.1.4.3 Processing Model
Software MUST apply the following rules in the order below to
ascertain the rules governing the content of "atom:content".
1. If the value is "TEXT", the content of atom:content MUST NOT
contain child elements. Such text is intended to be presented to
humans in a readable fashion. Thus, software MAY display it
using normal text rendering techniques such as proportional
fonts, white-space collapsing, and justification.
2. If the value of "type" is "HTML", the content of atom:content
MUST NOT contain child elements, and SHOULD be suitable for
handling by software that knows HTML. The HTML markup must be
escaped; for example, "<br>" as "<br>". The HTML markup
SHOULD be such that it could validly appear directly within an
HTML <DIV> element. Receiving software which displays the
content SHOULD use the markup to aid in displaying it.
3. If the value of "type" is "XHTML", the content of atom:content
MAY contain child elements. The content SHOULD be XHTML text and
markup that could validly appear directly within an xhtml:div
element. Receiving software which displays the content SHOULD
use the markup to aid in displaying it. Escaped markup is
interpreted as a text representation of markup, and MUST NOT be
interpreted as markup itself.
4. If the value of "type" ends with "+xml" or "/xml", the content of
atom:content may include child elements, and SHOULD be suitable
for handling by software that knows the indicated media type. If
the "src" attribute is not provided, this would normally mean
that the "atom:content" element would contain a single child
element which would serve as the root element of the XML document
of the indicated type.
5. If the value of "type" begins with "text/" the content of
atom:content MUST NOT contain child elements.
6. For all other values of "type", the content of atom:content MUST
be a valid Base64 encoding [RFC3548], which when decoded SHOULD
be suitable for handling by software that knows the indicated
media type. In this case, the characters in the Base64 encoding
may be preceded and followed in the atom:content element by
whitespace, and lines are separated by a single newline (U+000A)
character.
4.2 Metadata Elements
[[ Alphabetical listing of metadata elements... ]]
Extending Atom:
9. Extending Atom
9.1 Extensions To the Atom Vocabulary
Future versions of this specification may add new elements and attributes
to the Atom markup vocabulary. Software written to conform to this version
of the specification will not be able to process such markup correctly and,
in fact, will not be able to distinguish it from a markup error. For the
purposes of this discussion, unrecognized markup from the Atom vocabulary
will be considered "foreign markup".
Unlike markup from other vocabularies, foreign markup from the Atom
vocabulary MAY appear at any location in an Atom document.
9.2 Software Processing of Foreign Markup
Software processing an Atom Document which encounters foreign markup in a
location that is legal according to this specification MUST NOT stop
processing or signal an error. It may be the case that the software is able
to process the foreign markup correctly and does so. Otherwise, such markup
is termed "unknown foreign markup".
When unknown foreign markup is encountered in a Text Contruct or
atom:content element, software SHOULD ignore the markup and process any
text content of foreign elements as though the surrounding markup were not
present.
9.3 Extension Elements
Atom allows foreign markup anywhere in an Atom document. Child elements
of atom:entry and atom:feed are considered "metadata" elements, and are
described below. The role of other foreign markup is undefined by this
specification.
9.3.1 Simple Extension Elements
A Simple Extension element MUST NOT have any attributes or child
elements. The element MAY contain either character data, or be
empty.
The element can be interpreted as a simple property of the
container element that encloses it. The pair consisting of the
namespace-URI of the element and the local name of the element
can be interpreted as the name of the property. The character data
content of the element can be interpreted as the value of the property.
If the element is empty, then the property value can be interpreted as an
empty string.
9.3.2 Structured Extension Elements
The root element of a Structured Extension element MUST have at
least one attribute or child element. It MAY have attributes, it
MAY contain well-formed XML content (including character data), or
it MAY be empty.
The structure of a Structured Extension element, including the
order of its child elements, could be significant, so it MUST be
preserved by processors.
This specification does not provide an interpretation of a
Structured Extension element. The syntax of the XML contained in
the element, and an interpretation of how the element relates to
its Subject is defined by the specification of the Atom extension.
Remove "The atom:head element"
Impacts
Everything. PaceHeadInEntry is no longer needed. Dozens of other paces become obsolete or changed due to simplifying the data model.
Notes
Leaves unsolved the question of how an original entry can remain signed if an intermediary wants to insert additional elements of metadata. ... anonymous
-
Unsolved? Allowing other people to add or modify arbitrary information to an entry is precisely what signatures are intended to prevent. The goal should be to avoid changing the entry by providing a mechanism for encapsulation. ... RoyFielding
See Also: PaceEntriesElement
