RE: [xml-dev] Schema Namespace name, schemaLocation, and Schema V ersioning

["Dare Obasanjo" <dareo@microsoft.com>]

My $0.02 from an article I wrote a short while ago[0]

Versioning and Namespaces
--------------------------
There are two primary mechanisms used in practice to create different
versions of an XML instance document. One method is to use a version
attribute on the root element as is done in XSLT, while the other method
is to use the namespace name of the elements as the versioning
mechanism. Versioning based on namespaces is currently very popular,
especially with the W3C, who have used this mechanism for various XML
technologies including SOAP, XHTML, XML Schema, and RDF. The namespace
URI for documents that are versioned using the namespace is typically in
the following format:

      http://my.domain.example.org/product/[year/month][/area]

The primary problem with versioning XML documents by altering the
namespace name in subsequent versions is that it means XML
namespace-aware applications that process the documents will no longer
work with the documents, and will have to be upgraded. This is primarily
beneficial with document formats whose versions change infrequently, but
upon changing alter the semantics of elements and attributes, thus
requiring that all processors no longer work with the newer versions for
fear of misinterpreting them. 

On the other hand, there are a number of scenarios where an XML document
versioning mechanism based on a version attribute on the root element is
sufficient. A version attribute is primarily beneficial when changes in
the document's structure are backwards compatible. The following
situations are all areas where using a version attribute is a wise
choice: 

* Semantics of elements and attributes will not be altered. 
* Changes to the document involves the addition of elements and
attributes, but rarely removal. 
* Interoperability between applications with various versions of the
processing software is necessary. 

Both versioning techniques are not mutually exclusive and can be used
simultaneously. For instance, XSLT uses both a version attribute on the
root element, as well as a versioned namespace URI. The version
attribute is used for incremental, backwards-compatible changes to the
XML document's format, while altering the namespace name is done for
significant changes in the semantics of the document. 


[0] http://msdn.microsoft.com/library/en-us/dnexxml/html/xml05202002.asp

-- 
PITHY WORDS OF WISDOM 
The primary function of the design engineer is to make things difficult
for the fabricator and impossible for the serviceman.

This posting is provided "AS IS" with no warranties, and confers no
rights. 



> -----Original Message-----
> From: Jeni Tennison [mailto:jeni@jenitennison.com] 
> Sent: Wednesday, July 17, 2002 11:20 AM
> To: Mark Feblowitz
> Cc: 'CHIUSANO, Joseph'; 'Xml-Dev (E-mail)'; Duane Krahn 
> (E-mail); Satish Ramanathan (E-mail); Andrew Warren (E-mail); 
> Kurt A Kanaskie (Kurt) (E-mail); Michael Rowell (E-mail)
> Subject: Re: [xml-dev] Schema Namespace name, schemaLocation, 
> and Schema V ersioning
> 
> 
> Hi Mark,
> 
> > I also appreciate your comments on the impacts of markup changes on 
> > XSL (and, for that matter, any application). That is a potentially 
> > serious concern when altering the markup - that all XPath 
> expressions 
> > would have to be reviewed and updated. In a very general, very 
> > extensible substrate vocabulary, changes to the markup are 
> few and far 
> > between, and breakage would be rare (XSL for 
> manipulating/formatting 
> > .xsd files would be very stable for a very long time ;-). 
> For the rest 
> > of us, markup changes are harder to avoid. We try to reduce the 
> > likelihood of labor-intensive breakage by minimizing wholesale 
> > restructuring and keeping primarily to 
> additions/extensions. At least 
> > in these cases, we can leave much of the XPath untouched.
> 
> I think you've misunderstood me a little. I was trying to say that
> *if* you change the namespace every time you change the 
> version of a markup language, *and* you want the stylesheet 
> to keep on working with older versions of the markup language 
> then *as well as* any changes which might arise because of 
> the changes brought about because of the changes to the 
> markup language, you would have to change every XPath in the 
> stylesheet to cater to the change in the namespace.
> 
> Let me give you an example. Say you start off with the document:
> 
> <doc xmlns="http://www.example.com/doc/1.0";>Hello World!</doc>
> 
> and you have the stylesheet:
> 
> <xsl:stylesheet version="1.0"
>                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
>                 xmlns:doc="http://www.example.com/doc/1.0";>
> 
> <xsl:template match="/">
>   <xsl:apply-templates select="doc:doc" />
> </xsl:template>
> 
> <xsl:template match="doc:doc">
>   <html>
>     <head><title>Test</title></head>
>     <body><xsl:value-of select="." /></body>
>   </html>
> </xsl:template>
>                 
> </xsl:stylesheet>
> 
> Now let's say that our markup language changes its namespace:
> 
> <doc xmlns="http://www.example.com/doc/1.1";>Hello World!</doc>
> 
> Even without actual changes in the allowed content of the doc 
> element, to cope with both documents properly, a stylesheet 
> should look like:
> 
> <xsl:stylesheet version="1.0"
>                 xmlns:xsl="http://www.w3.org/1999/XSL/Transform";
>                 xmlns:doc.1.0="http://www.example.com/doc/1.0";
>                 xmlns:doc.1.1="http://www.example.com/doc/1.1";>
> 
> <xsl:template match="/">
>   <xsl:apply-templates select="doc.1.0:doc | doc.1.1:doc" /> 
> </xsl:template>
> 
> <xsl:template match="doc.1.0:doc | doc.1.1:doc">
>   <html>
>     <head><title>Test</title></head>
>     <body><xsl:value-of select="." /></body>
>   </html>
> </xsl:template>
>                 
> </xsl:stylesheet>
> 
> (There are other ways of doing it but they're all uglier.)
> 
> These are simple paths. If you had a path like:
> 
>   /doc:doc/doc:chapter/doc:section
> 
> things start getting so horrible that I don't even want to 
> write it because it would take too long.
> 
> So my point was about the effect that changing the namespace 
> of elements has on XSLT/XPath processing, not about the 
> effect of changing markup languages on XSLT/XPath processing. 
> Of course when you change a markup language the applications 
> that process it have to change; how much or how little 
> depends on the extent of the changes and the way the 
> application is designed to cope with the unexpected. But 
> discounting those kinds of changes, making changes to a
> *namespace* (and requiring that old versions are still 
> supported) can have huge and horrible consequences for a 
> stylesheet, or any namespace-aware application.
>   
> > In our case, the "proper version" approach that you suggest would 
> > likely cause breakage for our users. Any time a new version was 
> > promoted to the proper version, anyone who didn't know about and 
> > prepare for the change would experience breakage.
> 
> I think that depends on how you specify your markup language 
> and what rules you lay down about how applications should 
> deal with documents that are using an old (or new) version of 
> the markup language. For example, XSLT has a rule similar to 
> "if you encounter an element in the XSLT namespace, but you 
> don't recognise it, and the current version (as specified by 
> a version attribute) is greater than the one that you 
> support, then ignore the element". XSLT 2.0 also has a rule 
> like "if the version of the document is less than the most 
> recent one known to the application, then go into a 
> backwards-compatible mode and treat the document just as you 
> did before".
> 
> If you have those kinds of rule for applications that support 
> your markup language, then an application should treat:
> 
> <doc xmlns="http://www.example.com/doc";
>      version="1.0">Hello World!</doc>
> 
> in the same way whatever version an application currently 
> supports, and whatever version is "current".
> 
> There is an issue here to do with the schema to which these 
> documents point, because if they use a single central schema 
> location and the schema changes then of course the document 
> could become invalid. I think that this demonstrates that 
> schema locations should be tied to markup language versions. 
> For example:
> 
> <doc xmlns="http://www.example.com/doc";
>      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
>      xsi:schemaLocation="http://www.example.com/doc
>                          http://www.example.com/doc/2.3.1/doc.xsd";
>      version="2.3.1">Hello World!</doc>
> 
> > To recover (without doing a full upgrade), they'd have to 
> point at an 
> > older version *and* they have to alter their namespace 
> references, to 
> > reflect that they're using an older version.
> 
> As I suggested, a version attribute (or similar) to indicate 
> the version of the markup language being used in a particular 
> document is essential if you're not using the namespace name 
> to reflect the version of the markup language in use. With 
> that scheme, old documents would not have to be touched -- 
> they already state which version of the markup language they 
> comply to, and the namespace remains the same across 
> versions, so there's no need to change that.
> 
> It sounds as though my suggestion about having different 
> namespaces for documents adhering to draft specifications 
> wouldn't be appropriate in your case because from your 
> description there isn't a cycle of draft/discuss/accept in 
> the markup language development. If there's no difference 
> between the "latest" version and the "stable" version, then I 
> don't think there's a need for different namespaces for 
> different versions at all.
> 
> > And the "art" here is in assessing what part the validating parsers 
> > play in accepting/rejecting version differences. Remove version 
> > information from the namespace name and the validator plays 
> no direct 
> > role, at least when namespace names are compared. Add the version 
> > information and the validator plays a very direct role, rejecting 
> > mismatches and requiring interchangers to a priori agree on version.
> 
> I agree absolutely that you can use validating parsers to 
> ensure that documents comply to a particular version of a 
> markup language, but I don't agree that this has to be done 
> through the namespace name. For example, the schema for:
> 
> <doc xmlns="http://www.example.com/doc";
>      version="2.3.1">Hello World!</doc>
> 
> might be:
> 
> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema";
>            targetNamespace="http://www.example.com/doc";>
> 
> <xs:element name="doc">
>   <xs:complexType>
>     <xs:extension base="xs:string">
>       <xs:attribute name="version" use="required" fixed="2.3.1" />
>     </xs:extension>
>   </xs:complexType>
> </xs:element>
>            
> </xs:schema>
> 
> If you tried validating the document:
> 
> <doc xmlns="http://www.example.com/doc";
>      version="5.2.6">Hello World!</doc>
> 
> against this schema, you would get a very specific error 
> telling you that the version of the document does not match 
> the version of the schema.
> 
> Cheers,
> 
> Jeni
> 
> ---
> Jeni Tennison
> http://www.jenitennison.com/
> 
> 
> -----------------------------------------------------------------
> The xml-dev list is sponsored by XML.org 
> <http://www.xml.org>, an initiative of OASIS 
<http://www.oasis-open.org>

The list archives are at http://lists.xml.org/archives/xml-dev/

To subscribe or unsubscribe from this list use the subscription
manager: <http://lists.xml.org/ob/adm.pl>