Documenting Schemas

Because an XML schema is well-formed XML, you can include comments using XML comment syntax.

<!-- This is a comment -->

The XML parser does not pass comments to the application.

XML schema has three elements for schema meta data, for both application use and human readers.

Annotations allow you to make schemas self-documenting. By attaching a style sheet to the schema, you can create a readable version that explains the use of your schema.

Annotations

Annotations can appear anywhere in a schema to explain any element or attribute or type definition.

annotation element

The annotation element is the parent element for appinfo and documentation elements. This element can appear anywhere in the schema and allows you to document or comment on parts of your schema.

appinfo element

The appinfo element provides information for external applications, such as XML parsers. This element must be a child element of the annotation element.

documentation element

The documentation element allows you to place comments for human readers, such as copyright information, instructions about model group descriptions, and so on. This element must be child element of the annotation element.

Example

The following example shows an annotation that describes the purpose of the schema.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <xs:annotation>
      <xs:appinfo>Schema for processing submitted applications</xs:appinfo>
      <xs:documentation>
      Submitted applications for Human Resources department
      </xs:documentation>
   </xs:annotation>
</xs:schema>

Example

The following example shows an annotation to explain the purpose and application use of the relocationStatus element.

<xs:element name="relocationStatus">
   <xs:complexType>
      <xs:annotation>
         <xs:appinfo>
         If relocationStatus is Seattle, no further processing for relocationStatus is required.
         </xs:appinfo>
         <xs:documentation>
         This element is for determining relocation status to determine help determine costs.
         </xs:documentation>
      </xs:annotation>
   </xs:complexType>
</xs:element>