The final and critical step in developing an XML Schema is to eventually publish the schema to your business partners or even to the general public, depending on the intended audience. This is a critical part because the purpose of building XML Schemas is to make it possible for other developers and computer applications to interoperate with your application.
Although XML Schema files contain all the necessary information to describe your application’s content model, they are quite verbose and often difficult to grasp when they are complex. Annotations are a helpful XML Schema construct that provide documentation or human-readable commentary from the schema designer to someone else using the XML Schema. Annotations may be defined at the top level, immediately after the schema element, or at the top of any schema component defined within your XML Schema. The annotation element contains the documentation element, which has the author’s remarks within its body content. In XML Schema Design view, you can add annotations to any node in an XML Schema by double-clicking the node (typically either an element or a compositor). A cursor appears, and you can type documentation comments directly beneath the node. If you take a look at the XML Schema in Text view, you can see that XMLSPY has generated the required XML code at the correct location, as in the following example:
<xsd:annotation> <xsd:documentation>A Purchase Order Schema</xsd:documentation> </xsd:annotation>
You may also edit annotations from the Schema Overview page. XMLSPY provides a schema documentation generation utility that autogenerates either HTML or Microsoft Word files documenting your XML Schema. To run the documentation generator, choose Schema Design → Generate Documentation. Next, choose the desired output format and configure how you would like the documentation to appear. Click OK and specify the filename and path where you want to save the generated file. The generated documentation file includes the element name, a graphical representation, its data type, children, source definition, and any annotations (see Figure 4-16). In the case of HTML output, the file includes a hyperlinked navigation structure so that if you click on one of the children, the child element appears.
Figure 4-16: Generated documentation for the Purchase Order XML Schema example.
The documentation generation utility is a great way to keep your documentation in synch with the most recent XML Schema revision. The generated schema documentation files are ideally suited for conveying information about a complete and published XML Schema.