Presents your 
XML E-NEWSLETTER for January 29, 2003

<------------------------------------------->

MANAGE DIFFERENT VERSIONS OF DOCUMENTS

When developing applications that use XML data, you are often faced with
the dilemma of changing the XML structure. Sometimes the change is as
simple as adding a new element; other times it's more complex and even the
interpretation of existing elements is different. Dealing with different
versions of XML documents is a common problem with several potential
solutions.

MORE THAN ONE WAY

The central issue of this problem can be summed up with a short example.
Imagine you have an order system that maintains order data in XML, which
is stored in a database. At some point, the application grows to include
new features, which impact the XML document. Now you have old orders in
the "old" XML format, and new orders in a different XML format. How do
you tell the difference and process them appropriately?

MORE THAN CONVERSION

A first instinct is to perform a conversion of your old documents. This
can be a workable solution--provided the set of data in the old format is
static. But what if your system is integrated with other systems and
other vendors? Scheduling the "upgrade" to the new format is probably 
never going to happen in sync with everyone, which means that your 
application is going to have to handle multiple document formats.

ROOT ELEMENT ATTRIBUTE

The first possible solution to this problem is to incorporate an
attribute into the root element of the document that identifies the 
version. This is probably the simplest approach.

Suppose you have the following document:

<Order>
  <LineItem>
    <SKU>99823</SKU>
    <QTY>10</QTY>
    <Description>Super Widget</Description>
  </LineItem>
</Order>

Your system is going to be updated and the new application requires all
of the <LineItem> elements to be contained in a <LineItems> element. 
This is simple enough to accomplish, but how do you indicate to the
application which document is which format? Use an attribute on the 
root <Order>
element. For example:

<Order version="1.0">
  <LineItem>
    <SKU>99823</SKU>
    <QTY>10</QTY>
    <Description>Super Widget</Description>
  </LineItem>
</Order>

This snippet shows that the <Order> document is version 1.0. When XML
data is sent in the new format, it might look like this:

<Order version="2.0">
  <LineItems>
    <LineItem>
      <SKU>99823</SKU>
      <QTY>10</QTY>
      <Description>Super Widget</Description>
    </LineItem>
  </LineItems>
</Order>

Now when the application loads the document, it can look for the version
attribute. The attribute indicates which version the document adheres
to, allowing the application to know whether there should be a 
<LineItems>
element.

DIFFERENT DTDs

Another approach to this problem is to use DTDs to manage different
document versions or types. For example, the document above might be 
more fully described like this:

<?xml version="1.0"?>
<!DOCTYPE note SYSTEM "Order-1.0.dtd">
<Order>
  <LineItem>
    <SKU>99823</SKU>
    <QTY>10</QTY>
    <Description>Super Widget</Description>
  </LineItem>
</Order>

When a new version is developed, you change the DTD reference to the new
DTD definition. This approach allows the XML engine to be "aware" that
the documents are different, and can provide validation based on the
differences. The new version would look like this:

<?xml version="1.0"?>
<!DOCTYPE note SYSTEM "Order-2.0.dtd">
<Order>
  <LineItems>
    <LineItem>
      <SKU>99823</SKU>
      <QTY>10</QTY>
      <Description>Super Widget</Description>
    </LineItem>
  </LineItems>
</Order>

DIFFERENT NAMESPACES

Using namespaces approaches the problem similarly to DTDs. The namespace
defines a token that uniquely identifies the element "names" within a
particular "space". As the document type changes, you can specify a
different namespace--one that is unique and different from previous 
versions.
For example, using namespaces, our first document snippet might look 
like this:

<?xml version="1.0"?>
<Order xmlns="http://www.myserver.com/XML/Order-1.0">
  <LineItem>
    <SKU>99823</SKU>
    <QTY>10</QTY>
    <Description>Super Widget</Description>
  </LineItem>
</Order>

When you define a new document structure, you simply change the
namespace to reflect the new version. Using this approach, our new 
document might look like this:

<?xml version="1.0"?>
<Order xmlns="http://www.myserver.com/XML/Order-2.0">
  <LineItems>
    <LineItem>
      <SKU>99823</SKU>
      <QTY>10</QTY>
      <Description>Super Widget</Description>
    </LineItem>
  </LineItem>
</Order>

OTHER CONSIDERATIONS

There are a handful of other things you should consider when thinking
about XML versioning. One is how your application is going to respond to
multiple document versions. You can modify your program so that it knows
the difference between versions and processes them individually. Another
solution is to use XSL stylesheets to create new "views" of old documents.
This way, your old documents can be converted on the fly for your
application.

Another consideration is the way that versions are described. Common
approaches include a major/minor numbering scheme, such as 2.5. You can use
other version identifier schemes such as date stamps, which indicate not
only the version of the document type, but also its age and deployment date.

If you are using DTDs, then you will want to keep the older versions of
the DTD around. As documents continue to be stored in the older format,
you'll need the older DTDs to validate them.

Brian Schaffner is a senior consultant for Fujitsu Consulting. He
provides architecture, design, and development support for Fujitsu's 
Telcom360 group.

----------------------------------------