Annotations and Documentation

#1

Annotations

Annotations can be added to a schema to provide embedded documentation or application annotations.

There is an element call 'annotation' with two allowed child elements:

<xs:annotation>
<xs:documentation>
...
</xs:documentation>
<xs:appinfo>
...
</xs:appinfo>
</xs:annotation>

You can have an number of these 'documentation' or 'appinfo' elements.

#2

documentation/appinfo contents

These elements have mixed content.
They can contain elements from any namespace.
The 'documentation' element is for "user information".
The 'appinfo' element is for "application information".

#3

Where can they occur?

Anywhere inside the 'schema' or 'redefine' element and can occur multiple times.
As the first element of every other element--but only once.
Except it cannot occur inside the 'annotation' element.

#4

Documenting Your Schema

Document each global type and element declaration.
Document the schema with one annotation element.
Document your content models by adding information to each element reference/etc. as necessary.

#5

XHTML Annotations

You can use XHTML inside your schema to describe the elements/types/etc.

For example:

<xs:annotation>
<xs:documentation xmlns="http://www.w3.org/1999/xhtml">
<p>This schema is use to encode...</p>
</xs:documentation>
</xs:annotation>

You might want to define a prefix ('h' in the example below) for XHTML so you don't have to repeat the default namespace declaration:
```
<xs:annotation>
<xs:documentation>
<h:p>This schema is use to encode...</h:p>
</xs:documentation>
</xs:annotation>
```
Keep in mind that the default namespace is used to resolve unprefixed QNames in XML Schema.

#6

Example - Documenting a Complex Type

<xs:complexType name="Prolog">

    <xs:annotation>
      <xs:documentation>
      <h:p>This type represents a prolog element in a narrative document.</h:p>
      </xs:documentation>
    </xs:annotation>

    <xs:sequence>

      <xs:element name="pubdate" type="xs:date">
      <xs:annotation><xs:documentation>
      <h:p>The publication date of the containing document.</h:p>
      </xs:documentation></xs:annotation>
      </xs:element>

      <xs:element minOccurs="0" name="conference" type="md:Conference">
      <xs:annotation><xs:documentation>
      <h:p>An optional conference name for which the paper was written.</h:p>
      </xs:documentation></xs:annotation>
      </xs:element>

      <xs:element minOccurs="0" maxOccurs="unbounded" ref="md:author">
      <xs:annotation><xs:documentation>
      <h:p>The authors of the document.</h:p>
      </xs:documentation></xs:annotation>
      </xs:element>

      <xs:element minOccurs="0" name="abstract" type="xhtml:BlockBlockContainer">
      <xs:annotation><xs:documentation>
      <h:p>An abstract for the document.</h:p>
      </xs:documentation></xs:annotation>
      </xs:element>

      <xs:element minOccurs="0" name="acknowledgement" type="xhtml:BlockBlockContainer">
      <xs:annotation><xs:documentation>
      <h:p>Acknowledgments from the author.</h:p>
      </xs:documentation></xs:annotation>
      </xs:element>

      <xs:element maxOccurs="unbounded" minOccurs="0" name="category" type="md:CategoryDescriptor">
      <xs:annotation><xs:documentation>
      <h:p>ACM categories to which this document belongs.</h:p>
      </xs:documentation></xs:annotation>
      </xs:element>

      <xs:element minOccurs="0" name="terms">
        <xs:annotation><xs:documentation>
        <h:p>ACM terms that apply to this document.</h:p>
        </xs:documentation></xs:annotation>
        <xs:complexType>
          <xs:sequence>
            <xs:element maxOccurs="unbounded" name="term" type="md:GeneralTerm"></xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <xs:element minOccurs="0" name="keywords">
        <xs:annotation><xs:documentation>
        <h:p>ACM keywords that apply to this document.</h:p>
        </xs:documentation></xs:annotation>
        <xs:complexType>
          <xs:sequence>
            <xs:element maxOccurs="unbounded" name="word" type="xs:string"></xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>

      <xs:element minOccurs="0" name="copyright" type="md:Copyright">
        <xs:annotation><xs:documentation>
        <h:p>A copyright statement for this document.</h:p>
        </xs:documentation></xs:annotation>
      </xs:element>

    </xs:sequence>
  </xs:complexType>