UserPreferences

PaceFeedRecursive


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:

  1. XML containment relates feed and entry metadata to the data being described, thereby defining a consistent model for future extension elements;

  2. 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;

  3. Digital signatures can be safely applied to feeds and entries without needing special-case exceptions on how to recreate the signature after aggregation;

  4. 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&#x00F2;, 
      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&#x00F2;, 
      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 "&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.

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

See Also: PaceEntriesElement


CategoryProposals