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.
<xs:schema xmlns:xsi="http://www.w3.org/2001/XMLSchema"> <xs:annotation> <xs:documentation xml:lang="en-US"> Simple ...
Get XML in a Nutshell, 3rd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.