Annotating Schemas

In DTDs, you can use XML comments to add annotations and provide documentation. In schemas, you might expect that the situation would be a little more complex, and you'd be right. XML schemas define three additional elements that you use to add annotations to schemas: <xsd:annotation> , <xsd:documentation> , and <xsd:appInfo> .

Here's how things work: The <xsd:annotation> element is the container element for <xsd:documentation> and <xsd:appInfo> elements. The <xsd:documentation> element holds text of the kind you'd expect to see in a normal commentthat is, text designed for human readers. As its name implies, the <xsd:appInfo> element, on the other hand, holds annotations suitable for applications that read the document. Such applications can pick up information from <xsd:appInfo> elements if those elements are constructed in a way they recognize.

Here's an example using the <xsd:annotation> and <xsd:documentation> elements, adding an explanatory comment at the beginning of the ch05_07.xsd schema:

 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">  <xsd:annotation>   <xsd:documentation>   Book borrowing transaction schema.   </xsd:documentation>   </xsd:annotation>  .     .     . 

In fact, you can use the <xsd:annotation> element at the beginning of most schema constructions, such as the <xsd:schema> , <xsd:complexType> , <xsd:simpleType> , <xsd:element> , and <xsd:attribute> elements, and so on. Here's an example in which I've added an annotation to a complex type in ch05_07.xsd:

 <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">      <xsd:annotation>         <xsd:documentation>             Book borrowing transaction schema.         </xsd:documentation>     </xsd:annotation>     <xsd:element name="transaction" type="transactionType"/>  <xsd:complexType name="transactionType">   <xsd:annotation>   <xsd:documentation>   This type is used by the root element.   </xsd:documentation>   </xsd:annotation>  <xsd:sequence>             <xsd:element name="Lender" type="address"/>             <xsd:element name="Borrower" type="address"/>             <xsd:element ref="note" minOccurs="0"/>             <xsd:element name="books" type="books"/>         <xsd:sequence>         <xsd:attribute name="borrowDate" type="xsd:date"/>     </xsd:complexType>     .     .     . 

As we've seen with DTDs, you can create choices and sequences of elementsand as you might expect, you can do the same with schemas.