Annotating a Schema

Contact Us or call 1-877-932-8228
Annotating a Schema

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.

Next