Re: XML Schemas: Best Practices ? Versioning

[Mike_Leditschke@nemmco.com.au]

Hi Mary.

We had to make this decision about 12 months ago and decided
to use #2 as well as encoding the equivalent information into the
schemaLocation attribute.

This was driven mainly by a reading of section 4.3.2 of the Schema
structures document (as it was then), which implied that toolsets
might end up using the schemaLocation OR the namespace
to locate the schema. We figured we could always
freeze one or the other depending on how the best practices
evolved.

As it turned out, I'm glad we did include the version in the schemaLocation
as most of the tools to date have used this as the mechanism to
pick up the relavent schema.

Regards
Michael

<OffTopic>

I realise the best practices are about schemas but IMHO, the issue of
versioning the XML content needs to be considered as well, for a
versioning scheme to be effective. Naturally, this is domain specific

As an example, we also added a version
attribute on each transaction, within our transaction framework.
The driver here was that the transaction could become
disconnected from the document in which it was delivered, as multiple
transactions directed to multiple backend systems can be delivered
in a single document.

By attaching a version attribute to each transaction,
the backend processing can provide the appropriate logic switch for
different versions, without knowledge of the schema version under which
the transaction was delivered. This version attribute reflects the schema
version
at which the transaction structure last changed. This allows the schema
version
to progress without needing to touch the backend code to track these
changes,
except in the case where the application logic is affected.

</OffTopic>





                                                                                                                   
                    Mary                                                                                           
                    Pulvermacher         To:     xml-dev <xml-dev@lists.xml.org>                                   
                    <pulver@mitre        cc:     mctaylor@ingennia.com.au                                          
                    .org>                Subject:     XML Schemas: Best Practices ? Versioning                     
                                                                                                                   
                    06/09/2001                                                                                     
                    03:50 AM                                                                                       
                                                                                                                   
                                                                                                                   




Hello everyone-


Roger Costello has asked me to initiate this Best Practice topic.  The
results of this discussion will be posted, along with the other Best
Practices, on the Best Practice Homepage (
http://www.xfront.com/BestPracticesHomepage.html).


Topic:  What is the Best Practice for versioning XML schemas?


Is it better to version a schema by:
     1. Changing the (internal) schema version attribute,
     2. Changing the schema's targetNamespace,
     3. Changing the name of the schema, or
     4. Changing the location of the schema?



1. CHANGING THE SCHEMA VERSION ATTRIBUTE
In this approach one would simply change the number in the optional version
attribute at the start of the XML schema.  For example, in the code below
one could change version="1.0" to version="1.1"


<xs:schema  xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified"
    attributeFormDefault="unqualified"
    version="1.0">


This approach is very easy to use.  Also, no change is needed to the
instance document if it is not affected by the change in the schema.
However, the validator ignores this field.  Therefore, I regard the version
attribute as a cue to the human (especially if their schema doesn't
validate) rather than an enforceable constraint.  This approach could be
used in conjunction with any of the other approaches.



2. CHANGING THE SCHEMA'S TARGET NAMESPACE
In this approach, the 'targetNamespace' attribute at the start of the
schema could be changed to designate that a new version of the schema
exists.  One way to do this is to include a schema version number in the
designation of the target namespace as shown in the example below.


<xs:schema xmlns="http://www.addressGlobalsV1.0"
     targetNamespace="http://www.addressGlobalsV1.0"
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     elementFormDefault="qualified" attributeFormDefault="unqualified">


Then one could update the version number in the target namespace
designation with each change to the schema.  With this approach, instance
documents will not validate until they are changed to designate the new
targetNamepsace.


A disadvantage of this approach is that it forces all instance documents to
change, even if the change to the schema would not impact that instance.
Also, any schemas that 'include' this schema would have to change because
the target namespace of the included components must be the same as the
target namespace of the including schema.



3. CHANGING THE NAME OF THE SCHEMA
This approach changes the file name of the schema.  This should sound
familiar since most people develop conventions for naming their files so
that they know which version is the most current (e.g., append version
number or date to end of file name).


Since instance documents give the name and location of the associated
schema, the instance documents will not validate until they are changed to
designate the new schema file name.


As with option 2, one disadvantage of this approach is that it forces all
instance documents to change, even if the change to the schema would not
impact that instance.


Also, any schemas that import the modified schema would have to change
since the import statement provides the name and location of the imported
schema.


This approach seems most powerful when used in conjunction with approaches
1 and 4.  For example, one could set up a convention whereby the latest
version of a particular schema is always available in a specific location
under a specific filename.  The version number inside the schema (and any
annotations) could provide details on version number and a change history.
Old versions of the schema may still be made available in an archive.  This
approach seems most feasible to me for implementing XML schema registries.
With this approach, one always knows where to get the latest version but
small changes to the schema would not impact any schemas that 'inherit'
(include or import) the schema.


This mimics an approach taken by the W3C on the XML Schema specification.
For example, the latest version of the "XML Schema Specification Part 0:
Primer" is always called "xmlschema-0".  Previous versions are available
but the file names include a date to distinguish it from the latest
version.



4. CHANGING THE LOCATION OF THE SCHEMA
The last approach is changing the location of schema.  This is very similar
to changing the schema file name and really doesn't seem to make much sense
when used alone.  As mentioned above, a versioning approach that combines
this approach with options 1 and 3 seems powerful.



************ Your Opinion? ************


What is your opinion on the advantages and disadvantages of the respective
approaches?


Which approach do you think works best?


Are there other options I have missed?


Do you have a favorite way of handling schema versioning?  If so, why did
you choose this approach?



Please send your comments.  I'd love to hear from you.


Thanks in advance for your help.
Mary Pulvermacher
--
Mary K. Pulvermacher
The MITRE Corporation
pulver@mitre.org
(719) 572-8241
---------------------------------------------------










------------------------------------------
This e-mail is confidential.  If you are not the intended recipient, any use, disclosure or copying of this document is unauthorised and prohibited.  If you have received this document in error, please delete the email and notify me by return email or by phoning the NEMMCO Helpdesk on 1300 300 295.