UserPreferences

PaceExtensibilityAndVersioning


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:

End of inserted text

Out of scope

Discussion

Author

DaveOrchard


CategoryProposals