doc/schema.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/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 &XercesCName; mailing list
                 <jump href="mailto:&XercesCEmailAddress;">&XercesCEmailAddress; </jump>, and we
                 encourage the submission of bugs as described in
                 <jump href="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>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(XMLUni::fgSAX2CoreNameSpaces, true);
parser->setFeature(XMLUni::fgXercesSchema, 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="Associating 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 associate schemas with instance documents through
                  methods <code>setExternalSchemaLocation</code> if they use namespaces, and
                  <code>setExternalNoNamespaceSchemaLocation</code> otherwise.
                (For SAX2XMLReader, use the properties:
                "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 namespace:
               </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();
XMLCh* propertyValue = XMLString::transcode("personal.xsd");
ArrayJanitor&lt;XMLCh&gt; janValue(propertyValue);

parser->setProperty(
       XMLUni::fgXercesSchemaExternalNoNameSpaceSchemaLocation,
       propertyValue);
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 in <code>setExternalSchemaLocation</code> 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();
XMLCh* propertyValue = XMLString::transcode("http://my.com personal.xsd http://my2.com test2.xsd");
ArrayJanitor&lt;XMLCh&gt; janValue(propertyValue);

parser->setProperty(
       XMLCh XMLUni::fgXercesSchemaExternalSchemaLocation,
       propertyValue);
parser.parse("test.xml");
</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 namespace:
               </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 in xsi:schemaLocation attribute 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 http://my2.com test2.xsd"&gt;
...
&lt;/personnel&gt;
</source>
               </s3>
       </s2>
</s1>