XML in a Nutshell, 3rd Edition

Annotations

Now that there is a working schema, it’s good practice to include some documentary material about who authored it, what it was for, any copyright restrictions, etc. Since an XML Schema document is an XML document in its own right, one simple option would be to use XML comments to include documentary information.

The major drawback to using XML comments is that parsers are not obliged to keep comments intact when parsing XML documents, and applications have to do a lot of work to negotiate their internal structures. This increases the likelihood that, at some point, important documentation will be lost during an otherwise harmless transformation or edit. Encoding documentation as markup inline with the element and type declarations they refer to opens up endless possibilities for automatic documentation generation.

To accommodate this extra information, most schema elements may contain an optional xs:annotation element as their first child element. The annotation element may then, in turn, contain any combination of xs:documentation and xs:appinfo elements, which are provided to contain extra human-readable and machine-readable information, respectively.

The xs:documentation element

As a concrete example, let’s add some authorship and copyright information to the simple schema document, as shown in Example 17-4.

Example 17-4. address-schema.xsd with annotation

<xs:schema xmlns:xsi="http://www.w3.org/2001/XMLSchema"> <xs:annotation> <xs:documentation xml:lang="en-US"> Simple ...