Input into the versioning discussion

["G. Ken Holman" <gkholman@CraneSoftwrights.com>]

Thank you for chiming in on this, John.

At 2007-06-28 10:01 +0100, John Larmouth wrote:
>I am not taking any view on the proposed change, 
>but just want to caution against use of the 
>unqualified term "backwards compatible".
>
>NO-ONE NEED REPLY TO THIS MESSAGE - I AM NOT 
>WANTING TO START A FLAME.  IT IS JUST AN ACADEMIC COMMENT.

With useful timing, because of the recent 
discussions at the New York face-to-face 
regarding minor-versioning and "backwards compatibility".

>In this case, the change is from a version A 
>spec saying 0..1 to a version B spec saying 0..many.  This means that:
>
>a) Any document conforming to version A conforms to version B;
>
>b) Any system set up to generate a version A 
>document will continue to interwork with a 
>system set up to read and process a version B document;
>
>c) Any system set up to generate a version B 
>document will *fail* to interwork with systems 
>expecting a version A document, for any 
>documents that it generates outside of 0..1.
>
>This is, of course, quite obvious!

Indeed.

>There is, however, the additional question of 
>what the version A spec said that 
>implementations should do with unexpected additional material (extensibility).

This was brought up in NYC ... and what was 
discussed was the need for a processing model in 
order to massage instances of B into instances of 
A so that processes based on A can still work 
with A's information found in B.  And the way UBL 
is designed to be used, A can still be told that 
the instance that arrived is a B instance, so A 
can make the business decision to rely on A's 
information found in B or to throw an exception.

This makes a system supporting A forwards 
compatible in supporting instances of B.

I introduced this in the August 2006 Montréal 
face-to-face and after a number of revisions my 
ideas for NYC were summarized in:

   http://www.oasis-open.org/committees/document.php?document_id=23654

This concept of a processing model is consistent 
with the March 2007 W3C Tag document on XML 
vocabulary versioning, specifically section 2.1.2:

   http://www.w3.org/2001/tag/doc/versioning-20070326.html
   http://www.w3.org/2001/tag/doc/versioning-20070326.html#forwardsCompatible

>If the version A spec said "If you are expecting 
>0..1 and you get more than one, process the one 
>you have and give a silent warning", then you 
>know what a version A system will do when hit 
>with a document that conforms to version B but 
>not to version A, and that can be noted in the 
>version B spec.  If that statement is *not* 
>present in version A, then you are left guessing 
>on what might happen - perhaps total rejection of the entire document.

This can be a business rule ... or, with the 
processing model in place, the A system can 
accept a B instance limited to the information found in an A instance subset.

Interestingly, in every document type for UBL 
there is a UBLVersionID element available at the 
start of the document.  If an instance shows 2.2 
(say "B") and the system acting on the instance 
supports 2.1 (say "A"), the processed instance 
will have only 2.1 constructs but the 
UBLVersionID element will reveal the sender sent a 2.2 instance.

>It is always best to specify in version A what 
>is to be done with "illegal" documents that are 
>in various senses an "extension" of version A, 
>but people rarely bother to think about doing 
>that - they are too busy getting version A right!

Indeed ... but given that the UBL TC only 
specifies the document model, it is up to a 
community of users to document their expectations for each deployment.

>It is encouraged in ASN.1 (with explicit 
>notation) to make such provision where there are 
>constraints that might be relaxed in a future 
>version (such as 0..1, or addition of further 
>elements to a sequence), but I am not sure 
>(without checking) whether any provision was made in version A of UBL.

No such provision was made ... the work was 
published anticipating it would meet most needs, 
with the expectation that groups would feed back 
the need for improvements for inclusion in minor revisions.

>But coming back to my main thread:  It is 
>generally better to say that "the version B spec 
>permits all of the documents allowed by version 
>A, but also permits other documents that version 
>A implementations will neither generate nor be 
>able to process".  This is more verbose than use 
>of the term "backwards compatible", but is more explicit and clearer.

I suppose ... we can consider such wording when 
we document the NYC discussions on minor versioning.

>If there *was* extensibility provision in 
>version A, then you can be more explicit and say 
>"the version B spec permits documents that have 
>additional information to the version A 
>specification; version A implementations will 
>process the information that conforms to the 
>version A specification but will ignore the 
>additional version B information;  users of 
>version B should be aware of this limitation."

Note that we distinguish extensibility from minor 
revision releases:  there is an extensibility 
point in all UBL documents.  The very first 
optional element child of the document element is 
UBLExtensions under which a community of users 
can dictate the document model of any extension they wish.

>Again, depending on what was said in version A 
>about the actions to be taken on an extended 
>document (eg "Process version A stuff but send a 
>warning back to the originator about unprocessed 
>material", then the situation in version B 
>becomes much clearer, and the version B spec 
>needs to consider what to do when such a warning 
>comes back.  You can see that this gets into a rather tangled loop!

Indeed ... but such is the purview of a community 
of users and, I think, not of the UBL TC (other 
than, perhaps, the TC indicating that stating such is a good practice).

>Best advice is:
>
>a)      Do as much as you can in a version A 
>spec to support likely (but unknown) version B 
>extensions in a predictable manner (failing 
>that, get stuff into version B that relates to a future version C).

I'm not so sure very much will be know about B 
when publishing the details of A.

>b)      Spell out in version B what will happen 
>when trying to interwork with a version A implementation.

Indeed.

>Sorry this is a long mail, but making provision 
>in version A for a future version B (or if you 
>forgot to do that, making provision in version B 
>for a future version C) has long been a hobby-horse of mine.

And a fun ride it is ... this is very timely and 
I'm looking forward to any feedback you may have 
on the documents published by the TC in this 
regard.  Hopefully you might also consider 
participating in the discussions and contributing to the documents.

Thanks again, John!

. . . . . . . . . . . Ken

--
Upcoming hands-on training:  UBL Oct 1-3,5, Code lists Oct 2, 2007
World-wide corporate, govt. & user group XML, XSL and UBL training
RSS feeds:     publicly-available developer resources and training
G. Ken Holman                 mailto:gkholman@CraneSoftwrights.com
Crane Softwrights Ltd.          http://www.CraneSoftwrights.com/o/
Box 266, Kars, Ontario CANADA K0A-2E0    +1(613)489-0999 (F:-0995)
Male Cancer Awareness Aug'05  http://www.CraneSoftwrights.com/o/bc
Legal business disclaimers:  http://www.CraneSoftwrights.com/legal