Documenting XML Schema Definitions (XSDs)

The power of TechWriter comes from its ability to leverage information from your XML schema. In this topic we will show you how to document XML Schema Definitions (XSDs) by including comments directly within the XSD itself as an alternative to creating annotations within TechWriter. Comments can include simple text descriptions or richly formatted content depending on the comment model you wish to use.

Documenting Elements, Attributes and Types

XSDs include the annotation tag as part of the schema definition that can be used to create comments for elements, attributes and types. Simply include the annotation tag with your comments for each item you wish to document. Here is an example:

<xsd:simpleType name="ZipCodeType">
    <xsd:annotation>
       <xsd:documentation>Contains a 5-digit US ZIP code.</xsd:documentation>
    </xsd:annotation>
:
</xsd:simpleType>

Documenting Element Examples

You can specify the contents of your element examples right inside your XSD by including a documentation tag that has a source attribute set to "~Example". Here is an example:

<xsd:element name="ZipCode">
<xsd:annnotation>
<xsd:documentation source="~Example">
<ZipCode>
    <Zip5>90210</Zip5>
    <Plus4>3582/Plus4>
</ZipCode>
  </xsd:documentation>
</xsd:annotation>
        :
</xsd:element>

Be sure the encode any less than signs (<) or ampersands (&) properly so that your XSD will remain valid. Also note that any leading spaces will be preserved so that you have control over how the example is indented.

Formatting Options

In some instances, you may want to format your comments with multiple paragraphs, lists, links and other formatting options that are available when using TechWriter's Annotation editor. By using one of TechWriter's supported comment models, such as XHTML, you can apply formatting to the text using comment tags. In order to use comment tags you must select the proper comment model for your XSD from the Schema Settings dialog that is displayed when you add or edit a XSD for the project.