Annotations and modularization

Almost all XML Schema elements may be annotated with human and machine readable documentation. To this end, one can use the annotation element, to be inserted at the begining of the XML Schema element content. This element may contain one or more appinfo subelements, which are intended to contain information for software programs reading the schema, and one or more documentation subelements, which are used for human readable comments.

Both the appinfo and documentation elements may contain text and any well-formed XML markup. This is because the schema itself must be a well-formed XML document. Moreover, these attributes have a source attribute that can point to a URI providing external documentation. Finally, the documentation element has a xml:lang attribute to indicate the language in which the description is written.

As an instance, the following complex type has an appinfo element containing its definition in the DTD language and a documentation element containing a description in English. Notice that the < and > characters in the content of appinfo are escaped since the content must be well-formed:

  <xs:complexType name="bibliographyType">
    <xs:annotation>
      <xs:appinfo>
        &lt;!ELEMENT bibliography (article | book)*&gt;
      </xs:appinfo>
      
      <xs:documentation xmlns:xhtml="http://www.w3.org/1999/xhtml">
        This <xhtml:strong>complex type</xhtml:strong> describes a 
        bibliography made of any number of article or book items.
      </xs:documentation>
    </xs:annotation>
    
    <xs:choice minOccurs="0" maxOccurs="unbounded">
      <xs:element ref="article"/>
      <xs:element ref="book"/>
    </xs:choice>
  </xs:complexType>

Large schemas can be divided in different fragments. These fragments can be included in a schema document using the modularization elements of XML Schema. There are two main modularization elements that may appear as immediate children of the schema element:

<include schemaLocation="URI"/> This instruction includes the schema identified by the schemaLocation attribute in the current schema; the included schema must have the same target namespace as the current schema;
<import namespace="NS" schemaLocation="URI"/> This instruction includes the schema identified by the schemaLocation attribute in the current schema; the included schema has a different target namespace identified by the namespace attribute.

Notice that the included or imported schemas must be well-formed XML Schemas. For instance, we may split our schema into two schemas: the first part contains the element and attribute declarations (declaration.xsd), and the second part contains the type definitions (definition.xsd). We can then recompose the original schema as follows:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  
  <xs:include schemaLocation="declaration.xsd"/>
  <xs:include schemaLocation="definition.xsd"/>

</xs:schema>

Moreover, the next example imports the XML Schema for XHTML (we suppose to have this schema saved in a document named xhtml.xsd) and then defines a description element that may contain valid XHTML content. In particular the group Block.mix describes the content of the body element in XHTML:

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:xhtml="http://www.w3.org/1999/xhtml">
  
  <xs:import namespace="http://www.w3.org/1999/xhtml"
             schemaLocation="xhtml.xsd"/>
  
  <xs:element name="description" type="descType"/>
  
  <xs:complexType name="descType" mixed="true">
    <xs:sequence>
      <xs:group ref="xhtml:Block.mix"/>
    </xs:sequence>
  </xs:complexType>

</xs:schema>