Annotating XML Schemas
- To annotate XML schemas.
- To create HTML documentation from XML schemas.
Overview
One of the nice features of XML Schema is that comments about the schema itself can be made within built-in XML elements. This makes it possible to run a transformation against a schema to builds documentation in HTML or some other human-readable format.
Annotating a Schema
The xs:annotation element is used to document a schema. It can take two elements: xs:documentation and xs:appInfo, which are used to provide human-readable and machine-readable notes, respectively.
The xs:annotation element can go at the beginning of most schema constructions, including xs:schema, xs:element, xs:attribute, xs:simpleType, xs:complexType, xs:group, and xs:attributeGroup.
Both the xs:documentation and xs:appInfo elements can contain any content, including undeclared elements and attributes. This allows the schema author to insert elements (e.g, HTML elements) to structure or format the documentation.
The sample below shows an annotated XML schema.
Code Sample: AnnotatingXMLSchemas/Demos/Book.xsd
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="Annotation.xsl"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:group name="GroupName">
<xs:annotation>
<xs:documentation>
This group can be used with any element that represents a <b>person</b>.
It provides for FirstName, MiddleName (?), and LastName.
</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="FirstName" type="xs:string"/>
<xs:element name="MiddleName" type="xs:string" minOccurs="0"/>
<xs:element name="LastName" type="xs:string"/>
</xs:sequence>
</xs:group>
<xs:attributeGroup name="AttGroupPerson">
<xs:annotation>
<xs:documentation>
This attribute group can be used with any element that represents a
person. It provides for Title (?) and BirthYear (?).
</xs:documentation>
</xs:annotation>
<xs:attribute name="Title">
<xs:annotation>
<xs:documentation>
This optional attribute provides the title of the person in question.
There is no default value.
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Mr."/>
<xs:enumeration value="Ms."/>
<xs:enumeration value="Dr."/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="BirthYear" type="xs:gYear"/>
</xs:attributeGroup>
<xs:element name="Book">
<xs:annotation>
<xs:documentation>
Root Element. Contains the Title, Author, and Illustrator elements.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element name="Title" type="xs:string"/>
<xs:element name="Author">
<xs:annotation>
<xs:documentation>
The Author element contains the elements defined in the GroupName
element group followed by the Specialty element and the attributes
defined in the AttGroupPerson attribute group.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:group ref="GroupName"/>
<xs:element name="Specialty">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Mystery"/>
<xs:enumeration value="Humor"/>
<xs:enumeration value="Horror"/>
<xs:enumeration value="Childrens"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
<xs:attributeGroup ref="AttGroupPerson"/>
</xs:complexType>
</xs:element>
<xs:element name="Illustrator" minOccurs="0">
<xs:annotation>
<xs:documentation>
The Illustrator element contains the elements defined in the
GroupName element group and the attributes defined in the
AttGroupPerson attribute group.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:group ref="GroupName"/>
</xs:sequence>
<xs:attributeGroup ref="AttGroupPerson"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
Transforming an XML Schema for Documentation
The Annotation.xsl file in the Annotation/Demos folder is an XSLT document that can be applied to an annotated schema to create human-readable HTML documentation. The screenshot below shows what it produces when applied to Annotation/Demos/Books.xsd.
Annotating XML Schemas Conclusion
In this lesson of the XML Schema tutorial, you have learned to annotate XML schemas and to use the annotation to output HTML documentation.