This proposal provides for extensibility and versioning of Atom. This is an alternative proposal to Dave Orchard's PaceExtensibilityAndVersioning, and re-uses a great deal of the text from that proposal.
The major difference between the proposals is that this proposal uses both a namespace and a "version" element, while the other proposal does not use a "version" element.
Having a version element allows us to keep the Atom namespace constant for much longer. We know that Atom items are going to get handed around within systems, often without any MIME marking saying what they are. If we change the namespace, programs receiving Atom blobs without MIME content types won't recognize it as Atom. Thus, keeping the namespace stable is valuable to content readers.
The following text is to be inserted into the format specification
New format section 3.1.3 "must-understand" attribute The "must-understand" attribute indicates whether the parent element MUST be understood by Atom processors. The default value is false. If a future version of Atom has changes that must be understood by receiving parties, feeds and entries that include those changes MUST include the atom:must-understand attribute with a value of true.
Into each element description in 4.x ensure: XYZ type allows attributes from any namespace. XYZ type allows XML elements from any namespace.
Add section on extending and versioning
New section 7 Extending and Versioning Atom
This document describes just the core of the Atom format. There will undoubtedly be extensions to Atom in other documents. Each extension will use the standard XML extension method, namely to create a new namespace and have all the new elements and/or attributes in that namespace.
Atom allows any party to extend instances of Atom using a namespace other than the atom format namespace name. Future versions of Atom may make changes to it's namespace and/or qnames, and this is called "versioning".
An "optional change" means that existing software that doesn't understand or know about the change should not fail to process content with the optional change. A "required change" means that software that doesn't understand or know about the change MUST fail to process the content if it doesn't understand the change.
7.1 Stability of the Namespace and Version of Atom
The namespace prefix for the core of Atom is described in the section titled "Notational Conventions". That namespace is unlikely to ever change. The only time this namespace is expected to change is if a third type of Atom document (beyond Atom Feed and Atom Entry) is added to the Atom core. The namespace does not need to change if the semantics or syntax of atom:feed or atom:entry change.
The version string for the core of Atom is given in the section titled "version Attribute", and it applies to all elements and attributes described in this document. That version identifier may change in the future, but it is likely that it will not. There is long history in the IETF of protocols that have never changed version identifier, while there is also history of protocols that have changed version identifiers every few years.
Any future version of the Atom core that is backwards compatible with this version will use the same version string. An example is adding an optional element or attribute. The only time that the version identifier is expected to change is if elements are added to the core Atom, if any core element has an required attribute added, if any core element has an attribute removed, or if the required semantics of any part of an element in the core of Atom is changed. It is not clear at this time whether the Atom community will want such changes to appear in the Atom core (requiring a version number change) or as extensions to Atom.
Note that version identifiers are strings, not numbers. Determining which versions an Atom-reading program recognizes needs to be an exact-string match.
7.2 Processing model
An Atom-compliant processor MUST obey the following rules:
- If it encounters Atom-namespace markup from a version of Atom that it knows, but it does recognize the markup, it MUST NOT process any of the content and MUST return an error for the entire content.
- If it encounters Atom-namespace markup from a version of Atom that it does not know, it assumes that all such markup has "atom:must-understand" set to "false".
- If it encounters unknown but namespace-qualified XML attribute content, it assumes that all such markup has "atom:must-understand" set to "false".
- If it encounters unknown XML element content in any namespace where the atom:must-understand flag on the element is set to (or assumed to be) "false", it MUST ignore it and all it's descendents.
- If it encounters unknown XML element content in any namespace where the atom:must-understand flag on the element is set to "TRUE", it MUST NOT process any of the content and MUST return an error for the entire content.
7.3 Atom 3rd party extensibility
3rd parties are allowed to extend Atom. They MUST use namespace names they control. The default for 3rd party extensions is that they will be ignored by processors if the processor does not know about the extension, as defined by section 7.1. Element extensions may be marked with atom:must-understand to indicate that processor must fault if the extension is unknown.
7.4 Sample extensibility scenarios.
The following are some sample scenarios of extensibility and versioning.
7.4.1 Atom optional extension element
A subsequent version of Atom adds an optional element to entry called atom:foo. The format specification contains the definition of foo and the allowed/disallowed locations for foo. This may be safely ignored by all processors. The Atom version identifier is re-used.
7.4.2 Atom required extension element
A subsequent version of Atom adds a required element to atom:entry called atom:bar. The format specification contains the definition of bar and the allowed/disallowed locations for bar. This must be understood by all processors. A new version identifier is used. The definition of the element defines whether or not the element must be understood by processors that only know earlier versions.
7.4.3 Atom incompatible change
A subsequent version of Atom makes an incompatible change that is not an addition. This could be changing the semantics of existing elements or attributes, removing an attribute or element. Like in section 7.4.2, a new version identifier is used. The definition of the change defines whether or not the element must be understood by processors that only know earlier versions.
7.4.4 Third-party optional addition
A third party creates an extension called thirdpartyns:foo. Atom instances may contain thirdpartyns:foo in any of the extensibility points unless the third party has provided a format document that specifies otherwise. The definition of the addition defines whether or not the element must be understood by processors that do not recognize the extension, and thus whether atom:must-understand has to be set to true in that addition.
The version attribute is:
redundant to "must-understand" attributes on "version-indicating" elements,
not modular, so different areas of the core can not be independently updated,
inconsistent with how 3rd party extensions must indicate changes, and
not embeddable, so that contained entries can be "versioned" independently of the feeds they appear in.
A wholly new version of Atom, that previous version implementations must understand or fault, but doesn't require a new namespace, can be indicated like this:
A new version of Atom, that may be generally indicated to consumers but doesn't change semantics of the core, can be indicated like this:
A modular extension, that is optional for publishers to use in certain situations, and makes semantic changes to core elements, can be indicated like this:
Third parties must use the must-understand facility to indicate requirements, anyway, and can be indicated like this:
Version information that can be applied to contained elements (eg. atom:entry) can appear in and apply only to those (per the definition of their specification):
<feed xmlns="http://purl.org/atom/ns#"> ... <entry> <new-entry-version atom:must-understand="true" atom:applies-up-to="atom:entry"/> </entry> <entry> <!-- this entry can be republished without faulting the consumer --> </entry> </feed>
An example of the difference between a mandatory, independent module requirement and a "new" version would be in the case where you would normally have a linear progression:
Version 1 --> Version 2 --> Version 3
But "Version 3" makes required changes independent of "Version 2", thus it's reasonable that implementors could choose to implement the features from Version 3 independently of the features from Version 2. Proper version planning would have indicated that both "Version 2" and "Version 3" should instead be "Module 1" and "Module 2". A true version dependency can always be indicated by the most recent version indicator including must-understand="true", because its specification would indicate the prerequisite versions/modules.