Chapter 23: Versioning

Book examples

Example 23-1. Version 2.0 of a complex type

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           version="2.0">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer" minOccurs="0"/>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="size" type="SizeType"
                  maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="SizeType">
    <xs:simpleContent>
      <xs:extension base="xs:integer">
        <xs:attribute name="system" type="xs:token"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:schema>

Example 23-2. Backward-incompatible definition

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           version="2.1">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="size" type="SizeType" maxOccurs="3"/>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="description" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="SizeType">
    <xs:simpleContent>
      <xs:extension base="xs:positiveInteger">
        <xs:attribute name="system" type="xs:token"
                      use="required"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:schema>

Example 23-3. Backward-incompatible instance

<product>
  <number>557</number>
  <name>Short-Sleeved Linen Blouse</name>
  <size>0</size>
  <size>2</size>
  <size>4</size>
  <size>6</size>
</product>

Example 23-4. Backward-compatible definition

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           version="2.1">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer"
                  minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="name" type="xs:string" minOccurs="0"/>
      <xs:element name="size" type="SizeType"
                  maxOccurs="unbounded"/>
      <xs:element name="desc" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="SizeType">
    <xs:simpleContent>
      <xs:extension base="xs:decimal">
        <xs:attribute name="system" type="xs:token"/>
        <xs:attribute name="units" type="xs:token"/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>
</xs:schema>

Example 23-5. Version 2.0 of a forward-compatible complex type

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           version="2.0">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer" minOccurs="0"/>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="size" type="xs:integer"
                  maxOccurs="unbounded"/>
      <xs:any minOccurs="0" maxOccurs="unbounded"
              processContents="skip"/>
    </xs:sequence>
    <xs:anyAttribute processContents="skip"/>
  </xs:complexType>
</xs:schema>

Example 23-6. Version 2.1 of a forward-compatible complex type

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           version="2.1">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer" minOccurs="0"/>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="size" type="xs:integer"
                  maxOccurs="unbounded"/>
      <xs:element name="desc" type="xs:string"/>
      <xs:any minOccurs="0" maxOccurs="unbounded"
              processContents="skip"/>
    </xs:sequence>
    <xs:attribute name="dept" type="xs:token"/>
    <xs:anyAttribute processContents="skip"/>
  </xs:complexType>
</xs:schema>

Example 23-7. Forward-compatible instance

<product dept="WMN">
  <number>557</number>
  <name>Short-Sleeved Linen Blouse</name>
  <size>0</size>
  <desc>Our best-selling shirt</desc>
</product>

Example 23-8. Using a version number in a schema

Schema (prod.xsd):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           xmlns="http://datypic.com/prod"
           targetNamespace="http://datypic.com/prod"
           version="2.1">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer" minOccurs="0"/>
      <xs:element name="name" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Instance:

<product xmlns="http://datypic.com/prod"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://datypic.com/prod prod.xsd">
  <number>557</number>
  <name>Short-Sleeved Linen Blouse</name>
</product>

Example 23-9. Using a version number on individual schema components

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           xmlns="http://datypic.com/prod"
           targetNamespace="http://datypic.com/prod"
           xmlns:doc="http://datypic.com/doc"
           version="2.1">
  <xs:element name="product" type="ProductType" doc:version="2.0"/>
  <xs:complexType name="ProductType" doc:version="2.0">
    <xs:sequence>
      <xs:element name="number" type="xs:integer" minOccurs="0"/>
      <xs:element name="name" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
  <xs:element name="catalog" type="CatalogType" doc:version="2.1"/>
  <xs:complexType name="CatalogType" doc:version="2.1">
    <xs:sequence>
      <xs:element name="catalog_id" type="xs:string"/>
      <xs:element ref="product" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Example 23-10. Using a version number in the schema location

Schema (prod_2.1.xsd):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           xmlns="http://datypic.com/prod"
           targetNamespace="http://datypic.com/prod">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer" minOccurs="0"/>
      <xs:element name="name" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Instance:

<product xmlns="http://datypic.com/prod"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://datypic.com/prod prod_2.1.xsd">
  <number>557</number>
  <name>Short-Sleeved Linen Blouse</name>
</product>

Example 23-11. Using a version number in the instance

Schema (prod.xsd):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           xmlns="http://datypic.com/prod"
           targetNamespace="http://datypic.com/prod">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer" minOccurs="0"/>
      <xs:element name="name" type="xs:string"/>
    </xs:sequence>
    <xs:attribute name="version"/>
  </xs:complexType>
</xs:schema>

Instance:

<product xmlns="http://datypic.com/prod"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://datypic.com/prod prod.xsd"
         version="2.1">
  <number>557</number>
  <name>Short-Sleeved Linen Blouse</name>
</product>

Example 23-12. Using a version number in the namespace name

Schema (prod.xsd):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           xmlns="http://datypic.com/prod/2"
           targetNamespace="http://datypic.com/prod/2">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer" minOccurs="0"/>
      <xs:element name="name" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Instance:

<product xmlns="http://datypic.com/prod/2"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://datypic.com/prod/2 prod.xsd">
  <number>557</number>
  <name>Short-Sleeved Linen Blouse</name>
</product>

Example 23-13. Using multiple methods to indicate version number

Schema (schemas/prod/2.1/prod.xsd):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           elementFormDefault="qualified"
           xmlns="http://datypic.com/prod/2"
           targetNamespace="http://datypic.com/prod/2"
           version="2.1">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer" minOccurs="0"/>
      <xs:element name="name" type="xs:string"/>
    </xs:sequence>
    <xs:attribute name="version" type="xs:decimal"/>
  </xs:complexType>
</xs:schema>

Instance:

<product xmlns="http://datypic.com/prod/2"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://datypic.com/prod/2
                             schemas/prod/2.1/prod.xsd"
         version="2.1">
  <number>557</number>
  <name>Short-Sleeved Linen Blouse</name>
</product>

Example 23-14. One approach to deprecation

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:doc="http://datypic.com/doc"
           version="2.1">
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer"/>
      <xs:element name="name" type="xs:string"/>
      <xs:choice>
        <xs:element name="color" type="xs:NMTOKEN">
          <xs:annotation>
            <xs:documentation>Deprecated in
                favor of colorList.</xs:documentation>
            <xs:appinfo>
              <doc:deprecated>true</doc:deprecated>
            </xs:appinfo>
          </xs:annotation>
        </xs:element>
        <xs:element name="colorList" type="xs:NMTOKENS"/>
      </xs:choice>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Example 23-15. Using minVersion and maxVersion

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning">
  <xs:element name="product" vc:minVersion="1.3">
    <!-- a declaration that uses XML Schema 1.3 constructs -->
  </xs:element>
  <xs:element name="product" vc:minVersion="1.1"
                             vc:maxVersion="1.3">
    <!-- a declaration conformant to versions 1.1 and 1.2 -->
  </xs:element>
</xs:schema>

Example 23-16. Using implementation-defined types and facets

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:ext="http://example.org/extensions"
           xmlns:saxon="http://saxon.sf.net/">
  <xs:element name="anyOrdinalDate" type="ext:ordinalDate"/>
  <xs:element name="recentOrdinalDate" type="OrdinalDateIn2011"/>
  <xs:simpleType name="OrdinalDateIn2011">
    <xs:restriction base="ext:ordinalDate">
      <xs:minInclusive value="2011-001"/>
      <xs:maxInclusive value="2011-365"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:element name="size" type="SMLXSizeType"/>
  <xs:simpleType name="SMLXSizeType">
    <xs:restriction base="xs:token">
      <saxon:preprocess action="upper-case($value)"/>
      <xs:enumeration value="SMALL"/>
      <xs:enumeration value="MEDIUM"/>
      <xs:enumeration value="LARGE"/>
      <xs:enumeration value="EXTRA LARGE"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Example 23-17. Using vc:typeAvailable and vc:typeUnavailable

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:ext="http://example.org/extensions"
           xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning">
  <xs:element name="anyOrdinalDate" type="ext:ordinalDate"
              vc:typeAvailable="ext:ordinalDate"/>
  <xs:element name="anyOrdinalDate" type="xs:string"
              vc:typeUnavailable="ext:ordinalDate"/>
  <xs:element name="recentOrdinalDate" type="OrdinalDateIn2011"/>
  <xs:simpleType name="OrdinalDateIn2011"
                 vc:typeAvailable="ext:ordinalDate">
    <xs:restriction base="ext:ordinalDate">
      <xs:minInclusive value="2011-001"/>
      <xs:maxInclusive value="2011-365"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="OrdinalDateIn2011"
                 vc:typeUnavailable="ext:ordinalDate">
    <xs:restriction base="xs:string">
      <xs:pattern value="2011-\d{3}"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Example 23-18. Using vc:facetAvailable and vc:facetUnavailable

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:saxon="http://saxon.sf.net/"
           xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning">
  <xs:element name="size" type="SMLXSizeType"/>
  <xs:simpleType name="SMLXSizeType"
                 vc:facetAvailable="saxon:preprocess">
    <xs:restriction base="xs:token">
      <saxon:preprocess action="upper-case($value)"/>
      <xs:enumeration value="SMALL"/>
      <xs:enumeration value="MEDIUM"/>
      <xs:enumeration value="LARGE"/>
      <xs:enumeration value="EXTRA LARGE"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="SMLXSizeType"
                 vc:facetUnavailable="saxon:preprocess">
    <xs:restriction base="xs:token"/>
  </xs:simpleType>
</xs:schema>

Example 23-19. Using vc:facetAvailable

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:ext="http://example.org/extensions"
           xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning">
  <xs:element name="astring" type="ShortString"/>
  <xs:simpleType name="ShortString">
    <xs:restriction base="xs:string">
      <ext:maxLengthWithoutWhitespace value="5"
               vc:facetAvailable="ext:maxLengthWithoutWhitespace"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>