doc/schema.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "./dtd/document.dtd">
<s1 title="Schema">
       <s2 title="Introduction">
               <p>This package contains an implementation of the W3C XML Schema
                 Language, a recommendation of the Worldwide Web Consortium
                 available in three parts:
                 <jump href="http://www.w3.org/TR/xmlschema-0/">XML Schema: Primer</jump> and
                 <jump href="http://www.w3.org/TR/xmlschema-1/">XML Schema: Structures</jump> and
                 <jump href="http://www.w3.org/TR/xmlschema-2/">XML Schema: Datatypes</jump>.
                 We consider this implementation complete except for the limitations cited below.
               </p>

               <p>We would very much appreciate feedback on the package via the Xerces-C mailing list
                 <jump href="mailto:&XercesCEmailAddress;">&XercesCEmailAddress; </jump>, and we
                 encourage the submission of bugs as described in
                 <jump href="http://xml.apache.org/xerces-c/bug-report.html">Bug-Reporting</jump> page.
                 Please read this document before using this package.
               </p>
       </s2>
       <anchor name="limitation"/>
       <s2 title="Limitations">
         <ul>
            <li>No interface is provided for exposing the post-schema
            validation infoset , beyond
            that provided by DOM or SAX;</li>
            <li> The parser permits situations in which there is
            circular or multiple importing.  However, the parser only permits forward
            references--that is, references directed from the
            direction of the schema cited in the instance
            document to other schemas.  For instance, if schema A
            imports both schema B and schema C, then
            any reference in schema B to an information item from
            schema C will produce an error. Circular or multiple
            &lt;include&gt;s have similar limitations.</li>
            <li>Due to the way in which the parser constructs content
            models for elements with complex content, specifying large
            values for the <code>minOccurs</code> or <code>maxOccurs</code>
            attributes may cause a stack overflow or very poor performance
            in the parser.  Large values for <code>minOccurs</code> should be
            avoided, and <code>unbounded</code> should be used instead of
            a large value for <code>maxOccurs</code>.</li>
         </ul>
       </s2>

       <anchor name="interpretation"/>
       <s2 title="Interpretation of Areas that are Unclear or Implementation-Dependent">
         <ul>
            <li>We have interpreted the specs as requiring &lt;keyref&gt; Identity Constraints to refer to 
                &lt;key&gt; or &lt;unique&gt; identity constraints within the scope of the elements to which 
                the &lt;keyref&gt; is attached. This interpretation is at variance with the Schema Primer, which 
                contains an example with a &lt;keyref&gt; declared on an element used inside the element of its 
                corresponding &lt;key&gt;.
            </li>  
         </ul>
       </s2>

       <anchor name="usage"/>
       <s2 title="Usage">

               <p>Here is an example how to turn on schema processing in DOMParser
               (default is off).  Note that you must also turn on namespace support
               (default is off) for schema processing.
               </p>
<source>// Instantiate the DOM parser.
DOMParser parser;
parser.setDoNamespaces(true);
parser.setDoSchema(true);
parser.parse(xmlFile);
</source>
               <p>Usage in SAXParser is similar, please refer to the
               sample program 'samples/SAXCount/SAXCount.cpp' for further reference.
               </p>
               <p>Here is an example how to turn on schema processing in SAX2XMLReader
               (default is on).  Note that namespace must be on (default is on) as well.
               </p>
<source>SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
parser->setFeature(XMLString::transcode("http://xml.org/sax/features/namespaces"), true);
parser->setFeature(XMLString::transcode("http://apache.org/xml/features/validation/schema"), true);
parser->parse(xmlFile);
</source>
               <p>Review the sample file, 'samples/data/personal-schema.xml' and
               'samples/data/personal.xsd' for an example of an XML Schema grammar.
               </p>
       </s2>

       <anchor name="associate"/>
       <s2 title="Assocating Schema Grammar with instance document">
               <p>Schema grammars can be associated with instance documents in two ways.
               </p>

               <s3 title="Specifying Schema Grammar through method calls:">
               <p>An application developer may use the methods <code>setExternalSchemaLocation</code>
                if they use namespaces, and <code>setExternalNoNamespaceSchemaLocation</code> otherwise
                to associate schemas with instance documents.
                (For SAX2XMLReader, use the properites:
                "http://apache.org/xml/properties/schema/external-schemaLocation" and
                "http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation")
               </p>
               <p>Here is an example with no target namspace:
               </p>
<source>
// Instantiate the DOM parser.
DOMParser parser;
parser.setDoNamespaces(true);
parser.setDoSchema(true);
parser.setExternalNoNamespaceSchemaLocation("personal.xsd");
parser.parse("test.xml");

// Instantiate the SAX2 XMLReader.
SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
parser->setProperty(
       XMLString::transcode("http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation"),
       XMLString transcode("personal.xsd"));
parser.parse("test.xml");
</source>

               <p>Here is an example with a target namespace. Note that it is an error to specify a
                different namespace than the target namespace defined in the Schema.
               </p>
<source>
// Instantiate the DOM parser.
DOMParser parser;
parser.setDoNamespaces(true);
parser.setDoSchema(true);
parser.setExternalSchemaLocation("http://my.com personal.xsd http://my2.com test2.xsd");
parser.parse("test.xml");

// Instantiate the SAX2 XMLReader.
SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
parser->setProperty(
       XMLString::transcode("http://apache.org/xml/properties/schema/external-SchemaLocation"),
       XMLString transcode("http://my.com personal.xsd http://my2.com test2.xsd"));
parser.parse("test");
</source>
               </s3>
               <s3 title="Specifying Schema Grammar through attributes in the instance document:">
               <p>If schema grammar was not specified externally through methods,
                then each instance document that uses XML Schema grammars must specify the location of
                the grammars it uses by using an xsi:schemaLocation attribute if they use
                namespaces, and xsi:noNamespaceSchemaLocation attribute otherwise.
               </p>
               <p>Here is an example with no target namspace:
               </p>
<source>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;personnel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	   xsi:noNamespaceSchemaLocation='personal.xsd'&gt;
...
&lt;/personnel&gt;
</source>
               <p>Here is an example with a target namespace. Note that it is an error to specify a
                different namespace than the target namespace defined in the Schema.
               </p>
<source>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;personnel xmlns="http://my.com"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	   xsi:schemaLocation="http://my.com personal.xsd"&gt;
...
&lt;/personnel&gt;
</source>
               </s3>
       </s2>
</s1>