RE: XML Schemas: Best Practices ? Versioning

[Michael Brennan <Michael_Brennan@allegis.com>]

I don't think 3 and 4 are reliable. #3 makes the incorrect assumption that "instance documents give the name and location of the associated schema". This is undoubtedly the prevalent case, but as sound entity resolution mechanisms gain more widespread use, I'm inclined to believe there will be less and less of this. You cannot assume a consuming application is relying upon the "schemaLocation" attribute (or even paying any attention to it). I think changing the target namespace is the only reliable approach.

 

In spite of the complications it poses, I think #2 is the best practice. True, instance documents and schemas that include the relevant schema must change to reference the new version, but that is often a good thing. You don't want those references to indiscriminately change to reference a new schema without assurance that there are no incompatibility issues. Indeed, by changing the namespace, you can permit concurrent use of different versions of a schema, allowing users time to migrate to the new version as compatibility is assured.

-----Original Message-----
From: Mary Pulvermacher [mailto:pulver@mitre.org]
Sent: Wednesday, September 05, 2001 10:51 AM
To: xml-dev
Cc: mctaylor@ingennia.com.au
Subject: XML Schemas: Best Practices ? Versioning

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