UserPreferences

PaceMinimalVersioning


Abstract

This proposal describes the simplest possible extensibility and versioning framework for Atom documents that could possibly work.

Status

Open

Rationale

This proposal defines a class of error in Atom documents, for convenience named an "Atom Error". Secondly, it defines a condition called "unrecognized markup". Finally, it constrains the behavior of software processing Atom documents in the presence of Atom Errors and unrecognized markup. The result is that software will ignore unrecognized markup unless it can be certain that the markup is erroneous, or unless the markup is explicitly marked as "Must Understand".

It is not clear that other proposals which offer a more complex versioning/extensibility framework are sufficiently beneficial to make the trade-offs worthwhile.

Proposal

Replace section 4.1 as follows

Section 4.1 The "version" and "must-understand" attributes

The root of an Atom document (either "feed" or "entry") MUST have a "version" attribute whose value indicates the version of the Atom specification that the Atom document conforms to. The version identifier for this specification is "draft-ietf-atompub-format-02: do not deploy". The value of the "version" attribute is referred os the "Atom Version".

Specifications (such as this one) that govern Atom documents constrain the occurrence and order of elements in the Atom Namespace, and may constrain where elements and attributes in other namespaces, or in no namespace, are allowed to appear in Atom documents. Markup in an Atom Document not conforming to the specification identified by its Atom Version constitutes an "Atom Error". Examples include the appearance of elements and attributes in the Atom Namespace which are not defined by that version's specification, or the appearance of elements or attributes in any (or no) namespace in locations other than allowed in the specification.

Software which encounters an Atom Error SHOULD report the error and MAY cease processing. If the software does not cease processing, it MUST ignore and bypass the markup (and its content, if it is an element that is in error).

Software processing Atom documents may encounter "unrecognized markup". One example is an element or attribute in the Atom Namespace which is not known to the software but may not constitute an Atom Error because the software does not recognize the Atom Version of the document. Another example is an element or attribute in another namespace (or in no namespace) appearing in a place where such markup is legal but which is not described in the specification corresponding to the Atom Version and furthermore is not recognized by the software.

Any element in an Atom document may have an "atom:must-understand" attribute; its value must be one of "true" or "false". Note that this attribute, unlike all others specified here, is in the Atom Namespace.

If software processing an Atom document encounters an unrecognized element which has the "atom:must-understand" attribute present with a value of "true", it MUST report an error and cease processing.

If software processing an Atom document encounters an unrecognized element which does not have the "atom:must-understand" attribute present with a value of "true", it MUST NOT report an error or cease processing. It MUST bypass and ignore that element and its content.

If software processing an Atom document encounters an unrecognized attribute, it MUST NOT report an error or refuse to continue processing that document. It MUST ignore that attribute.

Proposed By

TimBray.

Impacts

Notes

There's no way to mark an attribute with "must-understand"