Subject: PaceExtensibilityAndVersioning

From: "David Orchard" <[email-masked]>
Date: Mon, 19 Jul 2004 10:57:34 -0700

http://www.intertwingly.net/wiki/pie/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 it's 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 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 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: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.  

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.).

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 3rd party optional addition

A 3rd party creates an extension called thirdpartyns:foo.  Atom instances may contain foo in any of the extensibility points unless the 3rd party has provided a format document that specifies otherwise.  The instance contains a mustUnderstand="false" or it is not set.

7.4.5 3rd party required extension

A 3rd party creates an extension called thirdpartyns:bar.  Atom instances may contain foo in any of the extensibility points unless the 3rd party has provided a format document that specifies otherwise. The instance contains a mustUnderstand="true".

7.4.6 3rd party extensions refered to by atom

A 3rd 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".

7.4.7 enumeration extensibility

Atom or a 3rd 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 3rd parties can create a new extension element and mark it mustUnderstood.  There is no mechanism for 3rd 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

== Discussion ==

== Author ==

DaveOrchard

----

CategoryProposals

Cheers,
Dave

---

From: Ken MacLeod <[email-masked]>
Date: 19 Jul 2004 15:31:22 -0500

> http://www.intertwingly.net/wiki/pie/PaceExtensibilityAndVersioning

+1

One thing I'm trying to think of is how we could model mustUnderstand
causing the faulting of individual entries, rather than an entire
feed.

Possibility #1:

    Restrict faulting to identified "top-level" elements.  If an
    extension should fault at both the feed level and at the element
    level, a mustUnderstand attribute must appear in both.  The
    corresponding feed-level mustUnderstand element may just be a
    placeholder for that purpose.

Possibility #2:

    Instead of true/false, we use feed/entry/none (default: none).

    Pass-through intermediaries could then pass-through entries marked
    with mustUnderstand="entry", but not entries marked with
    mustUnderstand="feed", since the intermediary itself must
    understand the effect on the feed from the one entry to be able to
    pass it on alone.

    Feed-level extensions would be always be feed/none.

    This possibility has the drawback in that it doesn't scale well to
    other top-level elements, that may in turn be cross-referenced to
    other top-level elements.

Possibility #3:

    Do nothing.  If the intermediary doesn't understand, it faults its
    source feed and doesn't pass on any entries.  If the intermediary
    does understand the scope of the extension element, and chooses to
    pass on an entry with mustUnderstand="true", it understands that
    downstream clients may fault the entire feed based on that entry.

  -- Ken