UserPreferences

PaceAggregationDocument


Abstract

Create a new option for the document element, <aggregation>, which can contain multiple feeds, and do away with head-in-entry.

Status

New proposal.

Rationale

PaceFeedRecursive addresses some important issues (see its rationale), but making feeds recursive, but only one level deep, doesn't feel like the right way to address them. This proposal similarly creates a container for multiple feeds, but does so by creating a new top level element, not by allowing feeds to contain feeds. This will help avoid confusion over whether a feed in a feed can contain a feed, and so on--something we decided long ago not to allow.

Note that this proposal also differs from PaceFeedRecursive in not eliminating atom:head. atom:head was added to the format before, and for reason not related to PaceHeadInEntry, and thus, discussion of whether to remove it might be best taken up separately from discussion of alternative solutions to the problem PaceHeadInEntry addressed.

Example

<?xml version="1.0" encoding="UTF-8"?>
<aggregation version="draft-ietf-atompub-format-06: do not deploy"
xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-06">
    <head>
    <title>My aggregation feed</title>
    <link href="http://example.org/agg/"/>
    <updated>2003-12-13T18:30:02Z</updated>
    <author>
      <name>John Doe</name>
    </author>
  </head>
  <feed>
    <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>
  </feed>
  <feed>
    <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>
    <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&#x00F2;, 
      my brother, sat among us for the last time.</div></summary>
      <updated>2004-12-13T18:30:02Z</updated>
    </entry>
  </feed>
</aggregation>


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&#x00F2;, 
      my brother, sat among us for the last time.</div></summary>
      <updated>2004-12-13T18:30:02Z</updated>
  </entry>
</feed>

Proposal

Create aggregation, which contains (feed*)

Keep feed as at present (metadata, entry*)

Change entry to contain (metadata, content)

Declare everything else to be metadata, whether standard (atom namespace) or future extensions (other namespaces).

in section 2:

2.  Atom Documents

   This specification describes three kinds of Atom Documents:  Atom Aggregation
   Documents, Atom Feed Documents, and Atom Entry Documents.

   An Atom Aggregation Document is a container for multiple Atom feeds.  Its
   document element is atom:aggregation.

   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 = atomAggregation | atomFeed | atomEntry

   All three 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.3 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:aggregation" Element

   The "atom:aggregation" element acts as a container for multiple
   feeds, enabling entries from multiple feeds to be combined into
   a single document, while maintaining the context provided by the
   feeds from which they originate.

   atomAggregation =
      element atom:aggregation {
         atomCommonAttributes,
         atomVersionAttribute,
         (atomHead
          & atomFeed*)
      }

   atom:aggregation elements MUST have a "version" attribute whose
   content indicates the version of the Atom specification that the
   aggregation conforms to.

   The version identifier for this specification is
   "draft-ietf-atompub-format-05: do not deploy".

   Its first element child MUST be atom:head, which MAY be followed
   zero or more atom:feed child elements.


4.1.3  The "atom:feed" Element

   The "atom:feed" element acts as a container for metadata and data
   associated with the feed.  This element can appear as a child of the
   atom:aggregation element, or it can appear as the document (i.e.,
   top-level) element of an Atom Feed Document.

   When appearing in an Atom Feed Document, atom:feed elements MUST
   have a "version" attribute whose content indicates the version of the
   Atom specification that the feed conforms to.

   The version identifier for this specification is
   "draft-ietf-atompub-format-05: do not deploy".

   atomFeed =
      element atom:feed {
         atomCommonAttributes,
         atomVersionAttribute?,
         atomHead,
         atomEntry*
       }

  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 exactly one atom:head element.
   o  atom:feed elements MAY contain any number of atom:entry elements.

4.1.4  The "atom:head" Element

   The "atom:head" element acts as a container for the metadata
   associated with a feed.

   The atom:head 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:head.

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

   o  atom:head elements MUST contain exactly one atom:title element.
   o  atom:head elements MUST contain at least one atom:link element
      with a rel attribute value of "alternate".
   o  atom:head 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 atom:head'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 containing feed.  atom:head elements MAY
      contain additional atom:link elements beyond those described above.
   o  atom:head 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:head elements MUST NOT contain more than one 
      atom:contributor element.
   o  atom:head elements MUST NOT contain more than one 
      atom:copyright element.
   o  atom:head elements MUST NOT contain more than one atom:id
      element.
   o  atom:head elements MUST contain exactly one atom:updated element.
   o  atom:head elements MAY contain any number of atom:category
      elements.
   o  atom:head elements MUST NOT contain more than one atom:post
      element.


4.1.5  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.6  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.6.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.6.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.6.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 "&lt;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.

Impacts

Everything. PaceHeadInEntry is no longer needed. Dozens of other paces become obsolete or changed due to simplifying the data model.

Notes

May be internally inconsistent in that the contents of atom:head are properties of atom:feed. Can we have an intermediate element as a container between the feed metadata and the feed element itself without violating the claims of the proposed section 2.1? If this is a problem, then we may need to do away with atom:head as proposed in PaceFeedRecursive if being consistent on this point is more important than the reasons for which atom:head was created.

Leaves unsolved the question of how an original entry can remain signed if an intermediary wants to insert additional elements of metadata. ... anonymous


CategoryProposals