6.4. Annotating Elements

Annotations are a great way to make notes about element types, attribute types, and almost any other element in an XML schema document. An annotation provides what a developer would typically call a “comment” to the XML schema document. Comments destined for developers are stored in a documentation subelement. appinfo subelements support automated processing of annotations—a discussion beyond the scope of this chapter.

Documentation in an XML schema document comes in two forms: annotations and comments. An annotation takes the form of an annotation element. The following annotation, which annotates the schema element, comes from the XML schema document address.xsd:

<xsd:annotation> 
    <xsd:documentation xml:lang="en"> 
        This XML Schema Document describes a customer 
        address in great detail.  In particular, this 
        document illuminates all of the attributes and  
        content options for elements and attributes. 
    </xsd:documentation> 
</xsd:annotation> 

A real comment, on the other hand, is an XML comment. An XML comment looks like this:

<!-- This is a comment --> 

Annotations have the advantage that they are preserved when creating a schema from schema documents. They provide a way to document any type of component. Any element, from the all-encompassing schema element to a local simple type nested in a local attribute type, can contain an annotation. A program can easily read an annotation and process the contents.

An XML comment is a way to provide documentation that might apply across elements or, perhaps, within an element. Comments have no particular format (other than the start and end punctuation characters, of course) and are not particularly associated with an element. Annotations are appropriate when describing the behavior of an element; XML comments are appropriate for providing guidance to other schema document maintainers.

Almost any element in an XML schema document may offer an annotation by specifying a nested annotation:

<xsd:simpleType name="partNameType" 
                final="list union" 
                id="catalog.partName.sType"> 
    <xsd:annotation> 
        <xsd:documentation xml:lang="en"> 
            A part name can be almost anything. 
            The name is a short description. 
        </xsd:documentation> 
    </xsd:annotation> 
    <xsd:restriction base="xsd:token" 
                     id="pnt-rst"> 
        <xsd:minLength value="1"/> 
        <xsd:maxLength value="40"/> 
    </xsd:restriction> 
</xsd:simpleType> 

An annotation is part of the element. Furthermore, the XML Schema Recommendation even specifies when an annotation is valid in the XML representation of an element. See the various “Content Options” sections of this book for explanations of applicability of the annotation subelement to each type of element is a schema.