Designing Extensible, Versionable XML Formats
July 21, 2004
An XML vocabulary should be designed in such a way that the applications that process it do not break when it is inevitably changed. One of the primary benefits of using XML for building data interchange formats is that the APIs and technologies for processing XML are quite resilient when faced with additions to vocabularies.
If I write an application that loads RSS feeds looking for item elements, then
processes their link and title elements using any one of the various technologies and APIs for
processing XML -- SAX, the DOM, or XSLT -- it is quite straightforward to build the
application so that it is unaffected by RSS specification changes as long as the link
and
title elements always appear in a feed.
However, this gives the false impression that there are no versioning issues to consider when designing XML formats, since you can always add elements and attributes to the format without causing harm. Experience has shown that this assumption is false. In fact, many of the same problems that face developers when versioning non-XML data formats affect XML-based formats as well.
This article explores some of the points to consider when versioning XML formats as well as some approaches to designing extensible XML formats in a manner compatible with existing XML technologies.
The Difference Between Versioning and Extensibility
Enabling extension of the format by programmers other than the designers of the format -- thus decentralizing the evolution of the format -- is a desirable feature and one that is often touted as an XML benefit. An example of the enabling nature of extensible XML formats is RSS 2.0 and the various modules that extend the functionality provided in the base specification. Designing a format so that it supports third-party extensions is the extensibility problem.
An XML format should be both backward and forward compatible. It should be backward compatible in that new versions of the format should also be valid instances of older versions of the format and thus not break any consumers of the original format.
It should be forward compatible in that older versions of the format should also be valid instances of newer versions of the format; so that old producers can work with consumers of the new format.
There are a four broad classes of changes that could occur in the process of transitioning from one version of a format to another.
1. New concepts are added (e.g., new elements or attributes added to format or new values for enumerations).
2. Existing concepts are changed (e.g., existing elements and attributes should be interpreted differently, added elements or attributes alter semantics of their parent/owning element).
3. Existing concepts are deprecated (e.g., existing elements and attributes should now issue a warning when consumed by an application).
4. Existing concepts are removed (e.g., existing elements and attributes should no longer work when consumed by an application).
Designing XML formats so that the above changes can occur between versions of a format, yet the format remains backward and forward compatible is, obviously, a big versioning problem.
Versioning differs from extensibility in two broad ways. The first major difference is that versioning mechanisms must support change in a linear fashion, while extensibility mechanisms must support change in a concurrent fashion. A versioning mechanism must offer a way to create a version 1, a backward-compatible version 2, a backward-compatible version 3, and so on.
On the other hand, rather than defining an evolutionary process, an extensibility mechanism provides a way to allow new data to show up side by side (or concurrently) with data for a given format. Secondly, changing an XML format by creating subsequent versions is usually done by the entity that controls the format, while extensions are typically added by third parties. In practice, this tends to mean that versioning is done by the owner of the namespace of the XML format.
An ideal XML vocabulary is both extensible and versionable.
Guidelines for Designing Extensible XML Formats
In the article Versioning XML Vocabularies, David Orchard provided some guidelines for designing extensible XML formats. The following guidelines are slightly modified from some of the guidelines in Orchard's article.
- XML formats should be designed to be extensible.
- Extensions must not use the namespace of the XML format.
- All XML elements in the format should allow any extension attributes, and elements with complex content should allow for extension elements as children.
- Formats that support extensibility must specify a processing model for dealing with extensions.
The guidelines above differ from those in David's article in a few key ways. The major difference is that the guideline about specifying a processing model for extensions is upgraded from a should to a must. The reason I changed this rule is that without explicit and consistent rules for consumers of the format when dealing with extensions, then interoperability across implementations will suffer.
Another difference is that the guideline about allowing extension elements specified that elements with simple content (i.e. text content) shouldn't be allowed to have extension elements. The following discussions explore each of the above guidelines in more detail.
Why XML formats should be designed to be extensible.
The primary benefit of allowing extensibility in a format is that it enables a format to evolve without requiring central control of the format. A secondary benefit is that it allows the format to stay focused and simple by pushing specialized or niche-use cases and complex solutions into optionally supported extensions.
An example of the benefit of designing a format to be extensible is RSS 2.0 and the various RSS modules. The core RSS specification defines how to provide basic information such as the title, description, and publication date of one or more entries in a syndication feed.
Various extensions have been designed that enable much richer functionality, such as providing information about the number of comments posted in response to an entry and mechanisms for retrieving the comments to an entry as a separate RSS feed. These extensions have proliferated without the need to modify the RSS specification yet are not mandatory -- so web sites and news aggregators do not have to bear the cost of implementing complex features if they just need simple content syndication.
Another showcase of the benefit of extensibility in XML formats is the W3C XML Schema recommendation. The XML Schema
recommendation allows one to place extensions to the specification either as
namespace-qualified attributes on elements in the XML schema namespace or as element
children of the xs:appinfo element.
Extensions to XML schema have been used to augment its functionality in a number of ways. One example is the ability to embed Schematron assertions in an XML schema to check constraints that are beyond the capability of W3C XML Schema. Another example, is the XML schema annotations used by Microsoft's SQLXML 3.0, which are used for mapping between XML and relational schemas.
Annotated schemas used by SQLXML 3.0 can still be used for validating XML documents but have the added benefit of also being used for shredding XML data into relational tables and vice-versa. These extensions increase the utility of XML Schema without increasing the complexity for all consumers of XML Schema documents since they are primarily beneficial in specialized scenarios.
It should be noted that extensibility is a double-edged sword. The fact that evolution of an extensible format is decentralized may harm interoperability in certain cases since not all clients will support the same extensions.
Why extensions must not use the namespace of the XML format.
There are two main reasons extensions must use their own namespace name. The first is that it is important that each family of extensions be distinguishable from the core components of the XML format and other extensions. Without providing such identification there is potential for naming conflicts between different extensions or between extensions and future additions to the core specification.
Secondly, there should be a straightforward way to go from identifying an extension to learning more about it. If the namespace name of the extensions is an HTTP URI that points to human- and machine-readable information about the extensions then it allows consumers of the format the chance to learn about the extensions they encounter.
Why all XML elements in the format should allow any extension attributes and extension elements.
Once the decision has been made to make a format extensible the next question is where one should allow extensibility. One could restrict the elements whose content model can be extended or annotated using attributes, but this may end up unnecessarily restricting the usefulness of extensions. Consider the following XML fragment:
<books xmlns='http://www.example.com/books'>
<book publisher="Addison Wesley">
<title>Mythical Man Month</title>
<author>Frederick Brooks</author>
<publication-date>1995-06-30</publication-date>
</book>
<book publisher="Apress">
<title>Programmer's Introduction to C#</title>
<author>Eric Gunnerson</author>
<publication-date>2001-06-30</publication-date>
</book>
</books
In the above document there are multiple areas where one could augment the information
provided. The book element could be extended with an ext:edition
attribute that indicates what edition of the book is being described. An
ext:price element could be added to the content model of book
elements describing the price of the book. The author element could be
augmented with an ext:is-editor, which is used on collected works such as
anthologies to indicate that the specified author was actually an editor. And so on.
The point is that in an XML format it is likely that a lot of the structured data (i.e. elements) in the document can be extended or annotated in a way that adds more value to the data being transmitted. Given this situation, it is likely that designers of XML formats may not be able to anticipate the various ways the data in a format may be augmented or annotated.
Thus, if the author(s) of an XML format restrict which elements can be augmented by extensions there is the possibility that useful extensions may be prohibited by such restrictions. Allowing all elements in the XML format to be extended ensures that no useful extensions are prohibited.
When authoring a schema for an XML format using W3C XML Schema, you use
xs:anyAttribute to allow extension attributes to appear on an element and
xs:any to allow extension elements to appear as children of an element.
Why formats that support extensibility must specify a processing model for dealing with extensions.
Another key decision that must be made once an XML format is deemed extensible is what the processing model should be for handling extensions in consumers of the format. As pointed out by David Orchard in his article, Designing XML Vocabularies, the most popular processing model for dealing with extensions has been the use of Must Ignore rules in combination with mustUnderstand constructs.
With Must Ignore rules in place consumers of the format are expected to ignore extensions they do not understand. In the case of extension elements this could take one of two forms. Presentation formats such as XHTML only ignore the unknown start and end tags for the extension elements but still process their contents. David calls this the Must Ignore Container rule. In most other situations, XML formats apply what David called the Must Ignore All rule where the extension element and its children are ignored by the consumer if they are not understood. This implies that ignoring extensions is not fatal to the application and the data they contain is not significant.
In certain cases, an extension could be introduced to an XML format that contains data that is significant to the application and should not be ignored by consumers of the format. This situation is especially likely in the case of XML formats that mainly act as containers or envelopes for more specialized data such as SOAP.
If such scenarios are to be supported then designers of the XML format should consider
adding mustUnderstand constructs to the vocabulary. An example of a
mustUnderstand construct is the SOAP mustUnderstand
attribute. The rules for the mustUnderstand attribute in SOAP are given
below.
The SOAP mustUnderstand global attribute can be used to indicate whether a
header entry is mandatory or optional for the recipient to process. The recipient
of a
header entry is defined by the SOAP actor attribute (see section 4.2.2). The value
of the
mustUnderstand attribute is either "1" or "0".
The absence of the SOAP mustUnderstand attribute is semantically equivalent to
its presence with the value 0. If a header element is tagged with a SOAP
mustUnderstand attribute with a value of 1, the recipient of that header
entry either MUST obey the semantics (as conveyed by the fully qualified name of the
element) and process correctly to those semantics, or MUST fail processing the message.
XML formats that intend to allow extensions that need to be understood by consumers
should
use a mustUnderstandconstruct such as a namespace attribute, which must appear
on the extension element.
Other processing models for extensions are possible. One approach could be making
the
mustUnderstand rule the default for the format, meaning that a consumer must
always fail if it does not understand an extension. Another approach could be restricting
the structure of extensions so that they can be provided to the end user in a consistent
manner. For example, restricting extensions to key-value pairs in XML configuration
files.
Using XML Schema to Design an Extensible XML Format
W3C XML Schema provides a number of features
that promote extensibility in XML vocabularies such as wildcards, substitution groups,
and
xsi:type. I've written about a number of techniques for adding extensibility
to XML formats using W3C XML Schema in my article, W3C XML Schema Design
Patterns: Dealing With Change. So as not to repeat myself, I will merely provide a
brief overview of the various options described in my previous article.
1. Using Wildcards to create open-content models: The wildcards
xs:any and xs:anyAttribute are used to allow the occurrence of
elements and attributes from specified namespaces into a content model. Wildcards
allow
schema authors to enable extensibility of the content model while maintaining a degree
of
control over the occurrence of elements and attributes. The most important attributes
for
wildcards are namespace and processContents. The
namespace attribute is used to specify the namespace from which elements or
attributes the wildcard matches can come from. The processContents attribute is
used to specify if and how the XML content matched by the wildcard should be validated.
2. Gaining flexibility from Substitution Groups and Abstract Elements: A substitution group contains elements that can appear interchangeably in an XML instance document in a manner reminiscent of subtype polymorphism in OOP languages. Elements in a substitution group must be of the same type or have types that are members of the same type hierarchy.
An element declaration that is marked abstract indicates that a member of its substitution group must appear in its place in the instance document. A schema designer can build an extensibility point into a schema by defining an abstract element, which must be replaced by subtypes defined as extensions that are members of the abstract element's substitution group.
3. Runtime polymorphism via xsi:type and Abstract Types: Abstract
types are complex type definitions that have true as the value of their
abstract attribute, which indicates elements in an instance document cannot
be of that type, but instead must be replaced by another type derived either by restriction
or extension. The xsi:type
attribute can be placed on an element in an XML instance document to change its type
as long
as the new type is in the same type hierarchy as the original type of the element.
Although
it's not necessary to use abstract types in conjunction with xsi:type, if a
generic format is being created for which most users will create domain specific extensions,
then they provide some benefit.
4. Using xs:redefine to update type definitions: The types in a
schema can be redefined in a process whereby the type effectively derives from itself.
xs:redefine, used for redefinition, performs two tasks. The first is to act
as an xs:include element by bringing in declarations and definitions from
another schema document and making them available as part of the current target namespace.
The included declarations and types must be from a schema with the same target namespace,
or
it must have no namespace.
Second, types can be redefined in a manner similar to type derivation with the new
definition replacing the old one. Type redefinition is pervasive because it not
only affects elements in the including schema but also those in the included schema
as well.
Thus all references to the original type in both schemas refer to the redefined type,
while
the original type definition is overshadowed. Using xs:redefine doesn't provide
extensibility in the traditional sense but instead allows one to effectively alter
the
definitions of types in a given schema.
Guidelines for Designing Versionable XML Formats
The following guidelines for designing XML formats in a way that makes them resilient in the face of changes in subsequent versions are also modified from those in David Orchard's Versioning XML Vocabularies article.
If the next version of a format is backward compatible with previous versions, then the old namespace name must be used in conjunction with XML's extensibility model.
A new namespace name must be used when backward compatibility is not permitted. That is, software must break if it does not understand the new language components.
Formats should specify a mustUnderstand model for dealing
with backward-incompatible changes to the format that don't change the namespace name.
The following discussions explore each of the above guidelines in more detail.
Why the same namespace name should be used for backward-compatible versions of a format.
The namespace name of an element or attribute is part of its identity. The name of an element or attribute is syntactically in the form of a qualified name, also known as a QName. The QName is an XML name, called the local name, optionally preceded by another XML name, called the prefix, and a colon (':') character. The prefix of a qualified name must have been mapped to a namespace URI through an in-scope namespace declaration, mapping the prefix to the namespace URI.
Although QNames are important mnemonic guides to determining what namespace the elements and attributes within a document are derived from, they are rarely important to XML processors. For example, the following three XML documents would be treated identically by a range of XML technologies including, of course, XML schema validators.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:complexType id="123" name="fooType"/> </xs:schema> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:complexType id="123" name="fooType"/> </xsd:schema> <schema xmlns="http://www.w3.org/2001/XMLSchema"> <complexType id="123" name="fooType"/> </schema>
The W3C XML Path Language recommendation describes an expanded name as a pair consisting of a namespace name and a local name. A universal name is an alternate term coined by James Clark to describe the same concept. To many XML applications, the universal name of the elements and attributes in an XML document is what is important, and not the values of the prefixes used in specific QNames.
This means that changing the namespace name of an XML vocabulary renames all the elements and global attributes to a namespace-aware XML application such as XPath, XSLT, XML parsers, and a host of other technologies. If the new version of the format is backward compatible with the original version of the format, then elements and global attributes should retain the same names so as not to break namespace-aware applications that consume the format.
Why a new namespace name must be used when backward compatibility is not permitted.
As mentioned in the previous section, changing the namespace name of an XML vocabulary renames all the elements and global attributes in the vocabulary. In certain cases, changes to an XML format can make it differ drastically from one version to the next in a backward-incompatible manner. In such cases, it is best to change the namespace name so namespace-aware XML applications rightly fail to identify the new version of the format as being the same as the original, and thus reject documents in the new format.
Why XML formats should specify a mustUnderstand model for dealing with
backward-incompatible changes to the format.
If a newer version of an XML format is not backward compatible with its predecessor, but does not use a new namespace name, then there should be a way to tell consumers of the format to error on changed or new constructs that they do not understand.
A simple solution is for the format to provide a version number, which on its root
element
can be tested by consumers before processing the XML document. In this case the
mustUnderstand model is that the consumer must understand all elements from
the target namespace of the format if it supports the version number specified on
the root
element.
In cases where new elements are added to the format that are not backward compatible
with
older versions of the format, it may be best for such elements to be tagged with a
mustUnderstand attribute. Doing this ensures that there is still some degree
of interoperability, because as long as the producer generates documents in the new
format
that do not contain the new constructs then all is well.
For example, imagine an XML-based query language that adds update constructs in a
newer
version (e.g. create, replace, update,
delete, etc.). In such a situation, a producer of the format that has
upgraded to the newer version can still generate documents that contain the original
query
constructs in the language without worrying about compatibility. However, if the producer
is
generating documents using the new constructs it adorns them with
mustUnderstand attributes whose value is "true," which indicates to older
clients that they are to fail if they don't understand how to perform a delete
(for example).
It should be noted that the mustUnderstand construct does not have to be an
attribute. A limitation of using an attribute is that it isn't easy to use it to mark
a new
attribute as having to be understood. Another drawback of using an attribute is that
it has
to be repeated on each occurrence of an element that must be understood. This is needlessly
repetitive if that element appears multiple times in a document. Another approach
could be
specifying a mustUnderstand element that identifies which new items must be
understood.
Using XML Schema to Design a Versionable XML Format
Although W3C XML Schema (WXS) has a number of features for designing extensible XML vocabularies, there isn't a similar plethora of features for designing versionable XML vocabularies. There are, however, general approaches to providing a versioning policy for an XML vocabulary that are compatible with WXS. The following approaches provide mechanisms for describing XML formats using WXS in a way that enables evolution in a backward-compatible way.
1. New constructs in a new namespace: The most straightforward versioning mechanism is to specify that additions to the format should be in a different namespace from the core components of the format. To make this backward compatible, the XML format should have an extensibility model with default Must Ignore rules for items outside the namespaces the consumer understands, in combination with mustUnderstand constructs.
The following examples show version 1 of XML schemas that describe a collection of books and an XML document that conforms to the schema.
BOOKS-CORE.XSD
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.com/books-core">
<xs:attribute name="mustUnderstand" type="xs:boolean" />
</xs:schema>
BOOKS-V1.XSD
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.com/books/v1"
xmlns:b1="http://www.example.com/books/v1">
<xs:element name="books">
<xs:complexType>
<xs:sequence>
<xs:element name="book" type="b1:bookType"
maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="version" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:complexType name="bookType">
<xs:sequence>
<xs:element name="title" type="xs:string" />
<xs:element name="author" type="xs:string" />
<xs:any namespace="##other" minOccurs="0"
maxOccurs="unbounded"
processContents="lax" />
</xs:sequence>
<xs:attribute name="publisher" type="xs:string" />
</xs:complexType>
</xs:schema>
BOOKS.XML
<books version="1.0"
xmlns="http://www.example.com/books/v1">
<book publisher="IDG books">
<title>XML Bible</title>
<author>Elliotte Rusty Harold</author>
</book>
<book publisher="Addison-Wesley">
<title>The Mythical Man Month</title>
<author>Frederick Brooks</author>
</book>
<book publisher="WROX">
<title>Professional XSLT 2nd Edition</title>
<author>Michael Kay</author>
<price xmlns="http://www.example.com/book/extensions">
24.99
</price>
</book>
</books>
The schema for the http://www.example.com/books/v1 namespace describes the
books element, which can contain one or more book elements that
have an author and title element, as well as a
publisher attribute. The content model of the book element
allows for zero or more elements from any namespace besides the target namespace of
the
schema to appear after the author and title elements. The schema
for the http://www.example.com/books-core namespace contains a
mustUnderstand attribute that must be added on extension elements or elements
from a future version of the format.
In the next version of the format, it is decided that an isbn element should
be added to the content model of the book element. Since all consumers and
producers of the Example.com XML Book Format won't upgrade at the same time there
will be
times when someone using version 2 of the format will not understand the isbn
element. Since the importance of the isbn element is dependent on the
application, it is decided that the isbn element can appear with a
mustUnderstand, indicating whether the application consuming the format must
know how to process ISBNs. This is the schema for version 2 of the format along with
a
sample document:
BOOKS-V1.XSD
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.com/books/v1"
xmlns:b1="http://www.example.com/books/v1"
xmlns:b2="http://www.example.com/books/v2">
<xs:import namespace="http://www.example.com/books/v2"
schemaLocation="books-v2.xsd" />
<xs:element name="books">
<xs:complexType>
<xs:sequence>
<xs:element name="book" type="b1:bookType"
maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="version" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:complexType name="bookType">
<xs:sequence>
<xs:element name="title" type="xs:string" />
<xs:element name="author" type="xs:string" />
<xs:element ref="b2:isbn" />
<xs:any namespace="##other" minOccurs="0"
maxOccurs="unbounded"
processContents="lax" />
</xs:sequence>
<xs:attribute name="publisher" type="xs:string" />
</xs:complexType>
</xs:schema>
BOOKS-V2.XSD
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.com/books/v2"
xmlns:core="http://www.example.com/books-core">
<xs:import namespace="http://www.example.com/books-core"
schemaLocation="books-core.xsd" />
<xs:element name="isbn">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute ref="core:mustUnderstand"
default="false"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
BOOKS.XML
<books version="2.0" xmlns="http://www.example.com/books/v1"
xmlns:p="http://www.example.com/book/extensions"
xmlns:v2="http://www.example.com/books/v2"
xmlns:bc="http://www.example.com/books-core">
<book publisher="HCI">
<title>A Child Called It</title>
<author>Dave Pelzer</author>
<v2:isbn bc:mustUnderstand="true">
1-55874-766-9
</v2:isbn>
<p:price>9.95</p:price>
</book>
</books>
The primary drawback of this approach is that core components of the format are not in the same namespace. This makes it tricky for applications or human readers of the format to differentiate between extensions and core aspects of the format that show up in a later version.
A secondary drawback is that although this approach is backward compatible (v2 documents
can be consumed by v1 clients), it is not forward compatible. The v2 schema states
that an
isbn is mandatory, which is not the case in v1. This means that a v1 document
will be rejected by a v2 client. Switching the isbn element to being optional
doesn't work because it makes the schema non-deterministic. It is non-deterministic
because
when an isbn element is seen, the validator cannot tell whether the sequence is
over. The element may be validated as the optional isbn element that follows an
author, or against the wildcard, which allows any element in a namespace
other than the target namespace to appear.
Both of these drawbacks are tackled by the approach described next.
2. Using version extensibility points: Conceptually, a data format is made versionable by providing a well-defined extensibility point where additions to the format are expected to appear. This functionality is provided in WXS using wildcards. However, in practice simply placing a wildcard at a particular point in a content model often leads to non-deterministic content models. The following example shows a non-deterministic schema that intuitively seems like it should work.
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.com/incorrect"
<!-- THIS TYPE IS NON-DETERMINISTIC -->
<xs:complexType name="bookType">
<xs:sequence>
<xs:element name="title" type="xs:string" />
<xs:element name="author" type="xs:string" />
<xs:element name="isbn" type="xs:string" minOccurs="0" />
<xs:any namespace="##targetNamespace ##other" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="publisher" type="xs:string" />
</xs:complexType>
</xs:schema>
As mentioned earlier, the problem with the above schema is that when an isbn
element is seen the validator cannot tell whether the sequence is over. This is because
the
element may be validated as the optional isbn element that follows an
author, or against the wildcard, which allows any element in a namespace
other than the target namespace to appear. This limitation is due to the Unique Particle
Attribution Constraint of XML schema.
To make usage of wildcards deterministic in such situations, you can provide delimiters or sentry elements around the wildcard that helps the validator determine when the elements to validate against the wildcard begin and when they end.
The following examples show version 1 of XML schemas that describe a collection of books and an XML document that conforms to the schema.
BOOKS-CORE.XSD
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.com/books-core">
<xs:element name="delimiter">
<xs:complexType />
</xs:element>
<xs:element name="end">
<xs:complexType />
</xs:element>
<xs:attribute name="mustUnderstand" type="xs:boolean" />
</xs:schema>
BOOKS.XSD
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.com/books"
xmlns:b="http://www.example.com/books"
xmlns:bc="http://www.example.com/books-core">
<xs:import namespace="http://www.example.com/books-core"
schemaLocation="books-core.xsd" />
<xs:element name="books">
<xs:complexType>
<xs:sequence>
<xs:element name="book" type="b:bookType"
maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="version" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:complexType name="bookType">
<xs:sequence>
<xs:element name="title" type="xs:string" />
<xs:element name="author" type="xs:string" />
<xs:element name="isbn" type="xs:string"
minOccurs="0" />
<xs:sequence minOccurs="0" maxOccurs="1">
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:element ref="bc:delimiter" />
<xs:any namespace="##targetNamespace ##local"
minOccurs="0" maxOccurs= "unbounded"/>
</xs:sequence>
<xs:element ref="bc:end" />
</xs:sequence>
<xs:group ref="b:extensionGroup" minOccurs="0" />
</xs:sequence>
<xs:attribute name="publisher" type="xs:string" />
</xs:complexType>
<xs:group name="extensionGroup">
<xs:sequence>
<xs:element name="extensions">
<xs:complexType>
<xs:sequence>
<xs:any namespace="##other" minOccurs="0"
maxOccurs="unbounded"
processContents="lax" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:group>
</xs:schema>
BOOKS.XML
<books version="1.0" xmlns="http://www.example.com/books">
<book publisher="IDG books">
<title>XML Bible</title>
<author>Elliotte Rusty Harold</author>
</book>
<book publisher="Addison-Wesley">
<title>The Mythical Man Month</title>
<author>Frederick Brooks</author>
<isbn>0-373-70708-8</isbn>
</book>
<book publisher="WROX">
<title>Professional XSLT 2nd Edition</title>
<author>Michael Kay</author>
<extensions>
<price xmlns="http://www.example.com/book/extensions">
24.99
</price>
</extensions>
</book>
</books>
The schema for the http://www.example.com/books/ namespace describes the
books element, which can contain one or more book elements that
subsequently have required author and title elements, an optional
isbn element, plus a publisher attribute. Each book
element also has an extensibility point within which a delimiter element
followed by zero or more elements from the target namespace can occur multiple times.
The end of the extensibility point is bounded by an end element. The content
model of the book element also allows for zero or more elements from any
namespace besides the target namespace of the schema to appear after the end
element. The schema for the http://www.example.com/books-core namespace
contains a mustUnderstand attribute, which must be added on extension elements
or elements from a future version of the format. The delimiter and
end elements are also defined in this schema.
In the next version of the format, it is decided to add an additional
edition-number element to the content model of the book element.
Below is the schema for version 2 of the format, along with a sample document.
BOOKS.XSD
<xs:schema elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.com/books"
xmlns:b="http://www.example.com/books"
xmlns:bc="http://www.example.com/books-core">
<xs:import namespace="http://www.example.com/books-core"
schemaLocation="books-core.xsd" />
<xs:element name="books">
<xs:complexType>
<xs:sequence>
<xs:element name="book" type="b:bookType"
maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="version" type="xs:string" />
</xs:complexType>
</xs:element>
<xs:complexType name="bookType">
<xs:sequence>
<xs:element name="title" type="xs:string" />
<xs:element name="author" type="xs:string" />
<xs:element name="isbn" type="xs:string"
minOccurs="0" />
<xs:sequence minOccurs="0" maxOccurs="1">
<xs:element ref="bc:delimiter" />
<xs:element name="edition-number"
type="xs:positiveInteger"
minOccurs="0" />
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:element ref="bc:delimiter" />
<xs:any namespace="##targetNamespace ##local"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:element ref="bc:end" />
</xs:sequence>
<xs:any namespace="##other" minOccurs="0"
maxOccurs="unbounded"
processContents="lax" />
</xs:sequence>
<xs:attribute name="publisher" type="xs:string" />
</xs:complexType>
</xs:schema>
BOOKS.XML
<books version="2.0" xmlns="http://www.example.com/books"
xmlns:p="http://www.example.com/book/extensions"
xmlns:bc="http://www.example.com/book-core">
<book publisher="HCI">
<title>A Child Called It</title>
<author>Dave Pelzer</author>
<isbn>1-55874-766-9</isbn>
<bc:delimiter />
<edition-number>1<edition-number>
<bc:end />
<extensions>
<p:price>9.95</p:price>
</extensions>
</book>
</books>
Unlike the New constructs in a new namespace approach, this approach keeps all
the core components of the format in a single namespace and is forward compatible
as well as
backward compatible. It should be noted that forward compatibility is dependent on
not
adding any new required constructs in future versions. Another benefit of this approach
is
that it obviates the need for having an explicit mustUnderstand construct since
you can simply specify that if a consumer encounters any unknown element from the
target
namespace of the format then it should result in a fatal error.
The primary drawback of using version extensibility points is that it makes both schemas and XML instances more verbose, and therefore potentially more confusing.