Datypic Logo

Definitive XML Schema

Priscilla Walmsley (pwalmsley@datypic.com)
2nd edition (September 2012)
Prentice Hall PTR; ISBN: 0132886723

Chapter 21: Schema Design and Documentation

Book Examples

Example 21-1. Schema for Russian Doll approach

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://datypic.com/prod"
           targetNamespace="http://datypic.com/prod"
           elementFormDefault="qualified">
  <xs:element name="catalog">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="product" maxOccurs="unbounded">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="number" type="xs:integer"/>
              <xs:element name="name" type="xs:string"/>
              <xs:element name="size">
                <xs:simpleType>
                  <xs:restriction base="xs:integer">
                    <xs:minInclusive value="2"/>
                    <xs:maxInclusive value="18"/>
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
            </xs:sequence>
            <xs:attribute name="dept" type="xs:string"/>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Example 21-2. Schema for Salami Slice approach

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://datypic.com/prod"
           targetNamespace="http://datypic.com/prod"
           elementFormDefault="qualified">
  <xs:element name="catalog">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="product" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="product">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="number"/>
        <xs:element ref="name"/>
        <xs:element ref="size"/>
      </xs:sequence>
      <xs:attribute name="dept" type="xs:string"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="number" type="xs:integer"/>
  <xs:element name="name" type="xs:string"/>
  <xs:element name="size">
    <xs:simpleType>
      <xs:restriction base="xs:integer">
        <xs:minInclusive value="2"/>
        <xs:maxInclusive value="18"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:element>
</xs:schema>

Example 21-3. Schema for Venetian Blind approach

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://datypic.com/prod"
           targetNamespace="http://datypic.com/prod"
           elementFormDefault="qualified">
  <xs:element name="catalog" type="CatalogType"/>
  <xs:complexType name="CatalogType">
    <xs:sequence>
      <xs:element name="product" type="ProductType"
                  maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer"/>
      <xs:element name="name" type="xs:string"/>
      <xs:element name="size" type="SizeType"/>
    </xs:sequence>
    <xs:attribute name="dept" type="xs:string"/>
  </xs:complexType>
  <xs:simpleType name="SizeType">
    <xs:restriction base="xs:integer">
      <xs:minInclusive value="2"/>
      <xs:maxInclusive value="18"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Example 21-4. Schema for Garden of Eden approach

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://datypic.com/prod"
           targetNamespace="http://datypic.com/prod"
           elementFormDefault="qualified">
  <xs:element name="catalog" type="CatalogType"/>
  <xs:complexType name="CatalogType">
    <xs:sequence>
      <xs:element ref="product" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  <xs:element name="product" type="ProductType"/>
  <xs:complexType name="ProductType">
    <xs:sequence>
      <xs:element ref="number"/>
      <xs:element ref="name"/>
      <xs:element ref="size"/>
    </xs:sequence>
    <xs:attribute name="dept" type="xs:string"/>
  </xs:complexType>
  <xs:element name="number" type="xs:integer"/>
  <xs:element name="name" type="xs:string"/>
  <xs:element name="size" type="SizeType"/>
  <xs:simpleType name="SizeType">
    <xs:restriction base="xs:integer">
      <xs:minInclusive value="2"/>
      <xs:maxInclusive value="18"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Example 21-5. Repetition of terms

<product>
  <prodNumber>557</prodNumber>
  <prodName>Short-Sleeved Linen Blouse</prodName>
  <prodSize sizeSystem="US-DRESS">10</prodSize>
</product>

Example 21-6. No repetition of terms

<product>
  <number>557</number>
  <name>Short-Sleeved Linen Blouse</name>
  <size system="US-DRESS">10</size>
</product>

Example 21-7. Less clear context

<letter>Dear <custName>Priscilla Walmsley</custName>,
Unfortunately, we are out of stock of the
<prodName>Short-Sleeved Linen Blouse</prodName> in size
<prodSize>10</prodSize> that you ordered...</letter>

Example 21-8. Same namespace in a schema

ord.xsd:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://datypic.com/all"
           targetNamespace="http://datypic.com/all"
           elementFormDefault="qualified">
  <xs:include schemaLocation="prod.xsd"/>
  <xs:include schemaLocation="cust.xsd"/>
  <xs:element name="order" type="OrderType"/>
  <xs:complexType name="OrderType">
    <xs:sequence>
      <xs:element name="customer" type="CustomerType"/>
      <xs:element name="items" type="ItemsType"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Example 21-9. Same namespace in an instance

<order xmlns="http://datypic.com/all"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://datypic.com/all ord.xsd">
  <customer>
    <name>Priscilla Walmsley</name>
  </customer>
  <items>
    <product>
      <number>557</number>
    </product>
  </items>
</order>

Example 21-10. Different namespaces in a schema

ord.xsd:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:prod="http://datypic.com/prod"
           xmlns:cust="http://datypic.com/cust"
           xmlns="http://datypic.com/ord"
           targetNamespace="http://datypic.com/ord"
           elementFormDefault="qualified">
  <xs:import schemaLocation="prod.xsd"
             namespace="http://datypic.com/prod"/>
  <xs:import schemaLocation="cust.xsd"
             namespace="http://datypic.com/cust"/>
  <xs:element name="order" type="OrderType"/>

Example 21-11. Different namespaces in an instance

<order xmlns="http://datypic.com/ord"
       xmlns:prod="http://datypic.com/prod"
       xmlns:cust="http://datypic.com/cust"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://datypic.com/ord ord.xsd">
  <customer>
    <cust:name>Priscilla Walmsley</cust:name>
  </customer>
  <items>
    <prod:product>
      <prod:number>557</prod:number>
    </prod:product>
  </items>
</order>

Example 21-12. Different namespaces in an instance, with default namespaces

<order xmlns="http://datypic.com/ord"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://datypic.com/ord ord.xsd">
  <customer>
    <name xmlns="http://datypic.com/cust">Priscilla Walmsley</name>
  </customer>
  <items>
    <product xmlns="http://datypic.com/prod">
      <number>557</number>
    </product>
  </items>
</order>

Example 21-13. Chameleon namespaces in a schema

ord.xsd:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://datypic.com/ord"
           targetNamespace="http://datypic.com/ord"
           elementFormDefault="qualified">
  <xs:include schemaLocation="prod.xsd"/>
  <xs:include schemaLocation="cust.xsd"/>
  <xs:element name="order" type="OrderType"/>
  <xs:complexType name="OrderType">
    <xs:sequence>
      <xs:element name="customer" type="CustomerType"/>
      <xs:element name="items" type="ItemsType"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Example 21-14. Qualified local names

<ord:order xmlns:ord="http://datypic.com/ord"
           xmlns:prod="http://datypic.com/prod">
  <ord:number>123123</ord:number>
  <ord:items>
    <prod:product>
      <prod:number>557</prod:number>
    </prod:product>
  </ord:items>
</ord:order>

Example 21-15. Unqualified local names

<ord:order xmlns:ord="http://datypic.com/ord">
  <number>123123</number>
  <items>
    <product>
      <number>557</number>
    </product>
  </items>
</ord:order>

Example 21-16. Schema for qualified local element names

ord.xsd:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:prod="http://datypic.com/prod"
           xmlns="http://datypic.com/ord"
           targetNamespace="http://datypic.com/ord"
           elementFormDefault="qualified">
  <xs:import schemaLocation="prod.xsd"
             namespace="http://datypic.com/prod"/>
  <xs:element name="order" type="OrderType"/>
  <xs:complexType name="OrderType">
    <xs:sequence>
      <xs:element name="number" type="xs:integer"/>
      <xs:element name="items" type="prod:ItemsType"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

prod.xsd:

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

Example 21-17. Invalid mixing of unqualified names and default namespace

<order xmlns="http://datypic.com/ord">
  <number>123ABBCC123</number>
  <items>
    <product>
      <number>557</number>
    </product>
  </items>
</order>

Example 21-18. Documentation

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:doc="http://datypic.com/doc">
  <xs:element name="product" type="ProductType">
    <xs:annotation>
      <xs:documentation xml:lang="en"
                     source="http://datypic.com/prod.html#product">
        <doc:description>This element represents a product.
        </doc:description>
      </xs:documentation>
    </xs:annotation>
  </xs:element>
  <!--...-->
</xs:schema>

Example 21-19. ISO 11179-based type definition

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:doc="http://datypic.com/doc">
  <xs:simpleType name="CountryType">
    <xs:annotation>
      <xs:documentation>
        <doc:name>Country identifier</doc:name>
        <doc:identifier>3166</doc:identifier>
        <doc:version>1990</doc:version>
        <doc:registrationAuthority>ISO</doc:registrationAuthority>
        <doc:definition>A code for the names of countries of the
          world.</doc:definition>
        <doc:keyword>geopolitical entity</doc:keyword>
        <doc:keyword>country</doc:keyword>
        <!--...-->
      </xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:token">
      <!--...-->
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Example 21-20. Code documentation

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:doc="http://datypic.com/doc">
  <xs:simpleType name="CountryType">
    <xs:annotation>
      <xs:documentation>
        <doc:author>Priscilla Walmsley</doc:author>
        <doc:version>1.1</doc:version>
        <doc:since>1.0</doc:since>
        <doc:see>
          <doc:label>Country Code Listings</doc:label>
          <doc:link>http://datypic.com/countries.html</doc:link>
        </doc:see>
        <doc:deprecated>false</doc:deprecated>
      </xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:token">
      <!--...-->
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Example 21-21. Section identifiers

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:annotation><xs:documentation><sectionHeader>
    ********* Product-Related Element Declarations ***************
  </sectionHeader></xs:documentation></xs:annotation>
  <xs:element name="product" type="ProductType"/>
  <xs:element name="size" type="SizeType"/>
  <xs:annotation><xs:documentation><sectionHeader>
    ********* Order-Related Element Declarations *****************
  </sectionHeader></xs:documentation></xs:annotation>
  <xs:element name="order" type="OrderType"/>
  <xs:element name="items" type="ItemsType"/>
  <!--...-->
</xs:schema>

Example 21-22. Application information

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:app="http://datypic.com/app">
  <xs:element name="product" type="ProductType">
    <xs:annotation>
      <xs:appinfo>
        <app:dbmapping>
          <app:tb>PRODUCT_MASTER</app:tb>
        </app:dbmapping>
      </xs:appinfo>
    </xs:annotation>
  </xs:element>
  <!--...-->
</xs:schema>

Example 21-23. Non-native attributes

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:doc="http://datypic.com/doc"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://datypic.com/doc doc.xsd">
  <xs:element name="product" type="ProductType"
           doc:description="This element represents a product."/>
  <!--...-->
</xs:schema>

Example 21-24. A schema for non-native attributes

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns="http://datypic.com/doc"
           targetNamespace="http://datypic.com/doc">
  <xs:attribute name="description" type="xs:string"/>
</xs:schema>

Example 21-25. RDDL for the product catalog namespace

<?xml version='1.0'?>
<!DOCTYPE html PUBLIC "-//XML-DEV//DTD XHTML RDDL 1.0//EN"
                      "rddl/rddl-xhtml.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:rddl="http://www.rddl.org/">
<head><title>Product Catalog</title></head>
<body><h1>Product Catalog</h1>
  <div id="toc"><h2>Table of Contents</h2>
    <ol>
      <li><a href="#intro">Introduction</a></li>
      <li><a href="#related.resources">Resources</a></li>
    </ol>
  </div>