facebook google plus twitter
Webucator's Free XML Schema Tutorial

Lesson: Annotating XML Schemas

Welcome to our free XML Schema tutorial. This tutorial is based on Webucator's Introduction to XML Schema course.

Lesson Goals

  • 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 an XML Schema

Duration: 10 to 15 minutes.

In this exercise, you will annotate the schema you created in the "Tying It All Together" exercise.

  1. Open the schema you created in the "Tying It All Together" and save it in the AnnotatingXMLSchemas/Exercises directory.
  2. Annotate the schema as you see fit.
  3. Paste the following line of code under the XML declaration at the top of the schema.
    <?xml-stylesheet type="text/xsl" href="Annotation.xsl"?>
  4. Open the schema in Internet Explorer or Netscape to see the HTML documentation.