Abstract
This proposal provides for extensibility and versioning of Atom. The format rules are roughly: re-use namespace names when possible, ie compatible change, follow the "Must Ignore unknown extensions" rule, and provide "mustUnderstand" attribute for extensibility, change namespaces when making breaking, ie incompatible, changes.
Proposal
The following text is to be inserted into the format specification
New format section 3.1.3 "mustUnderstand" attribute The "mustUnderstand" attribute indicates whether the parent element MUST be understood by Atom processors. The default value is false.
Into each element description in 4.x ensure: XYZ type allows attributes from any namespace. XYZ type allows XML elements from any namespace.
Remove section 4.1
New section 7 Extending and Versioning Atom
Atom allows any party to extend instances of Atom using a namespace other than the atom format namespace name. Atom may make changes to its namespace and/or qnames, and this is called versioning. This section describes the processing model, extensibility and namespace models for extensibility and versioning.
An optional change means that existing software that doesn't know about the change should not break. A required change means that software that doesn't know about the change must break if it doesn't understand the change. The meaning of "understanding" is up to the change owner. It typically means at least a human has read a specification and/or software can validate the type according to the type definition.
7.1 Processing model
All atom compliant processor MUST ignore any unknown namespace qualified XML attribute content. All atom compliant processor MUST ignore any unknown XML element content in any namespace and all it's descendents UNLESS the atom:mustUnderstand flag on the element is set to "true". An atom compliant processor MUST process all elements marked with mustUnderstand="true" or process none at all. A Fault must be generated if any element marked mustUnderstand is not understood.
7.2 Atom namespace management policy
Any future version of Atom that is backwards compatible with this version will use this namespace name. An example is adding an optional element or attribute. Any backwards compatible version of Atom may use the version attribute to indicate the particular version of the compatible language.
Any future version of Atom that is incompatible with this version will either use a different namespace name or will use an element name not defined in this specification. An example is adding a required element/attribute or removing an element or attribute.
7.3 Atom third party extensibility
Third parties are allowed to extend Atom. They MUST use namespace names they control. The default for third 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:mustUnderstand 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 namespace is re-used. Optionally, the version attribute is changed.
7.4.2 Atom required extension element
A subsequent version of Atom adds a required element to 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 atom namespace name is used for all the existing atom names (feeed, entry, bar, etc.). The version number associated with the new atom namespace name is reset to the first version identifier, as defined by the version identifier.
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. As per 7.4.2, a new atom namespace name is used.
7.4.4 Third party optional addition
A third party creates an extension called thirdpartyns:foo. Atom instances may contain foo in any of the extensibility points unless the third party has provided a format document that specifies otherwise. The instance contains a mustUnderstand="false" or it is not set.
7.4.5 Third party required extension
A third party creates an extension called thirdpartyns:bar. Atom instances may contain foo in any of the extensibility points unless the third party has provided a format document that specifies otherwise. The instance contains a mustUnderstand="true".
7.4.6 Third party extensions refered to by atom
A third party creates an extension called thirdpartyns:author. Atom instances may contain thirdpartyns:author in a specific location. The atom format specification contains the allowed/disallowed locations for thirdpartyns:author and refers to the third party definition of author. In the case of a mandatory extension, a new atom namespace name is minted OR the extension is marked with mustUnderstand="true". In the case of optional extensions, the rules of section 7.4.1 are followed (namespace name re-used and optional version attribute change).
7.4.7 enumeration extensibility
Atom or a third party create an additional attribute value, such as extending the "rel" type. If this is optional, it may be simply added in. If mandatory to be understood then Atom has the opportunity to create a new qname for the extended attribute. Atom and third parties can create a new extension element and mark it mustUnderstood. There is no mechanism for third party to add in a mandatory enumeration value.
7.5 schema languages for extensibility
XML Schema, RelaxNG, and RDF/OWL each provide different capabilities for extensibility and versioning. There is discussion about which languages to use to specify machine readable constraints on Atom
XML Schema has particular difficulty in allowing elements to be mixed in at the same level as existing elements in extension namespace. A wildcard is not allowed at the same level as an optional element (in the same namespace) because of the "Unique Particle Attribution Rule". This problem, and a solution, is described in http://www.pacificspirit.com/Authoring/Compatibility/ExaminingElementWildcardSiblings.html.
Atom must do one of the following wrt extensibility and schema languages:
-
Using XML Schema, the format must use mechanisms in addition to wildcards to enable schema creation, ie extension elements
-
Using XML Schema, the schema is not revised for backwards compatible extensions or versions.
-
Does not use XML Schema
End of inserted text
Out of scope
-
Protocol extensibility (New verbs for Feed, Edit, Post URIs, new URIs + verbs )
-
Supporting in a backwards compatible way the removal of elements/attributes. There is no need for an XSLT style versioning model for testing for a version number and switching between instances.
-
Supporting arbitrary transformations between newer types and older types. There is no need for shipping an XSLT with an instance to transform it to an older version.
-
different extensibility models for different linktype
-
Grouping multiple extensions and versions into a single specification aka profile