This proposal modifies atompub-format-03 to provide a simple "Must Understand" facility. It removes the "version" attribute and adds an atom:must-understand child element of the root element, which contains a list of namespaces which processing software must understand or refuse to process the Atom document.




There is a good case for a "Must Understand" facility in Atom. In particular for those who wish to extend Atom with markup from other namespaces, it may be advantageous to restrict processing of feeds or entries to those clients which know the extensions.

However, allowing the placement of a "Must Understand" signal at arbitrary places in an Atom document creates complexity for implementors. Consider the case of a feed one of whose entries contains a "Must Understand" marker; it needs to be specified whether software which does not understand is forbidden from processing the individual entry or the whole feed, which requires a careful specification of what it means to "process". If it is the case that a "Must Understand" signal prevents feed processing, this would require software to read the whole feed, including all entries, before beginning any processing.


  1. Remove section 4.1, "version" attribute, along with the second and third paragraphs of section 5.

  2. Replace the last paragraph of section 2 with new sections 2.1 and 2.2 as follows.

2.1 "atom:must-understand" Element

Any Atom document MAY contain a single atom:must-understand element, which, if it appears, MUST be the first child element of the document element.

atom:must-understand can contain any number of atom:ns elements and MUST NOT contain any other child elements or non-white-space text content. Each atom:ns element MUST contain only text, with no child elements, which is to be interpreted as an XML namespace name [XMLNS]. These namespace names identify XML vocabularies which software must be able to process correctly in order for the Atom document to be processed correctly.

The Atom namespace name MUST NOT appear in any atom:ns element.

Software which is processing an Atom document with an atom:must-understand element MUST examine the namespace names in the atom:ns elements, and if it encounters any that identify markup vocabularies that it does not recognize or is not able to process correctly, it MUST NOT process the Atom document, and SHOULD signal an error condition.


  <ns></ns>  <!-- SVG required -->

2.2 Limitations of atom:must-understand

The atom:must-understand element provides no way to require correct processing of markup from in the Atom namespace or that is in no namespace. Thus, if future versions of this specification introduce new markup for which correct processing is required, it will be necessary that they be in an XML namespace other than Atom's.

For similar reasons, there is no way to require correct processing of XML vocabularies, such as RSS 2.0, which are in no XML namespace.


AFAIK, the only historical use of mandatory extensions is to graft privacy and licensing restrictions onto an existing protocol (which failed miserably, of course). Anticipating such extensions within an access protocol makes sense. I do not think it makes sense to place must-understand extensions within the data format, since enforcing privacy or copyright after the representation has been received is pointless (the legal issues are already handled by the copyright notice). Are there some concrete examples that can be used as scenarios? - RoyFielding


TimBray (with advice from Dave Orchard)