Chapter 6: Schema documentation and extension

Book examples

Example 6-1. Documentation

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

Example 6-2. Application information

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:app="http://example.org/app">
  <xsd:element name="product" type="ProductType">
    <xsd:annotation>
      <xsd:appinfo>
        <app:dbmapping>
          <app:tb>PRODUCT_MASTER</app:tb>
        </app:dbmapping>
      </xsd:appinfo>
    </xsd:annotation>
  </xsd:element>
</xsd:schema>

Example 6-3. Validating documentation

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:doc="http://example.org/doc"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://example.org/doc doc.xsd
                                http://www.w3.org/2001/XMLSchema
                                http://www.w3.org/2001/XMLSchema.xsd">
  <xsd:element name="product" type="ProductType">
    <xsd:annotation>
      <xsd:documentation xml:lang="en"
        source="http://example.org/prod.html#product">
        <doc:description>This element represents a product.
        </doc:description>
      </xsd:documentation>
    </xsd:annotation>
  </xsd:element>
</xsd:schema>

Example 6-4. A schema for user documentation

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns="http://example.org/doc"
            targetNamespace="http://example.org/doc">
  <xsd:element name="description" type="TextType"/>
  <xsd:complexType name="TextType" mixed="true">
    <!--...-->
  </xsd:complexType>
</xsd:schema>

Example 6-5. Non-native attributes

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

Example 6-6. A schema for non-native attributes

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

Example 6-7. ISO 11179-based type definition

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:doc="http://example.org/doc">
  <xsd:simpleType name="CountryType">
    <xsd:annotation>
      <xsd: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>
        <!--...-->
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
    <!--...-->
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

Example 6-8. Code documentation

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:doc="http://example.org/doc">
  <xsd:simpleType name="CountryType">
    <xsd:annotation>
      <xsd: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://example.org/countries.html</doc:link>
        </doc:see>
        <doc:deprecated>false</doc:deprecated>
      </xsd:documentation>
    </xsd:annotation>
    <xsd:restriction base="xsd:token">
    <!--...-->
    </xsd:restriction>
  </xsd:simpleType>
</xsd:schema>

Example 6-9. Section identifiers

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

Example 6-10. Instance with co-constraint

<customer newCustomer="false">
  <id>A123</id>
  <name>Priscilla Walmsley</name>
</customer>

Example 6-11. Schema without co-occurrence constraints

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:complexType name="CustomerType">
  <xsd:sequence>
    <xsd:element name="id" type="xsd:string" minOccurs="0"/>
    <xsd:element name="name" type="xsd:string"/>
  </xsd:sequence>
  <xsd:attribute name="newCustomer" type="xsd:boolean"/>
</xsd:complexType>
<xsd:element name="customer" type="CustomerType"/>
</xsd:schema>

Example 6-12. Schematron embedded in XSDL

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:sch="http://www.ascc.net/xml/schematron">
<xsd:complexType name="CustomerType">
  <xsd:sequence>
    <xsd:element name="id" type="xsd:string" minOccurs="0"/>
    <xsd:element name="name" type="xsd:string"/>
  </xsd:sequence>
  <xsd:attribute name="newCustomer" type="xsd:boolean"/>
</xsd:complexType>
<xsd:element name="customer" type="CustomerType">
  <xsd:annotation>
    <xsd:appinfo>
      <sch:schema>
        <sch:pattern name="customerIDs">
          <sch:rule context="customer[@newCustomer='false']">
            <sch:assert test="id">If not a new customer, should
              have an id.</sch:assert>
          </sch:rule>
          <sch:rule context="customer[id]">
            <sch:assert test="@newCustomer='false'">If has an
                id, should not be a new customer</sch:assert>
          </sch:rule>
        </sch:pattern>
      </sch:schema>
    </xsd:appinfo>
  </xsd:annotation>
</xsd:element>
</xsd:schema>

Example 6-13. Schema Adjunct Framework in XSDL

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:saf="http://www.extensibility.com/namespaces/saf"
            xmlns:db="http://example.org/dbmap">
  <xsd:annotation>
    <xsd:appinfo>
      <saf:schema-adjunct target="prod.xsd">
        <saf:document>
          <db:server>155.210.0.5</db:server>
          <db:database>PROD_MASTER_DB</db:database>
        </saf:document>
        <saf:element context="product">
          <db:table>PRODUCT_HEADER</db:table>
        </saf:element>
        <saf:element context="product/name">
          <db:column>PROD_NAME</db:column>
        </saf:element>
        <saf:attribute context="product/@effDate">
          <db:column>PROD_EFF_DATE</db:column>
        </saf:attribute>
      </saf:schema-adjunct>
    </xsd:appinfo>
  </xsd:annotation>
  <xsd:element name="product" type="ProductType"/>
  <!--...-->
</xsd:schema>

Example 6-14. Using a notation in an instance

<picture fmt="jpeg">47494638396132003200F7FF00FFFFFFFFFFCCFFFF99FF
FF66FFFF33FFFF00FF</picture>

Example 6-15. Declaring notations and notation attributes

<xsd:notation name="jpeg" public="JPG"/>
<xsd:notation name="gif" public="GIF"/>
<xsd:simpleType name="PictureNotationType">
  <xsd:restriction base="xsd:NOTATION">
    <xsd:enumeration value="jpeg"/>
    <xsd:enumeration value="gif"/>
  </xsd:restriction>
</xsd:simpleType>
<xsd:element name="picture">
  <xsd:complexType>
    <xsd:simpleContent>
      <xsd:extension base="xsd:hexBinary">
        <xsd:attribute name="fmt" type="PictureNotationType"/>
      </xsd:extension>
    </xsd:simpleContent>
  </xsd:complexType>
</xsd:element>

Example 6-16. A notation with an unparsed entity

Schema:

<xsd:element name="picture">
  <xsd:complexType>
    <xsd:attribute name="location" type="xsd:ENTITY"/>
  </xsd:complexType>
</xsd:element>
<!--...-->

Instance:

<!NOTATION jpeg SYSTEM "JPG">
<!ENTITY prod557 SYSTEM "prod557.jpg" NDATA jpeg>
<!ENTITY prod563 SYSTEM "prod563.jpg" NDATA jpeg>
]>
<catalog>
  <product>
    <number>557</number>
    <picture location="prod557"/>
  </product>
  <product>
    <number>563</number>
    <picture location="prod563"/>
  </product>
</catalog>