| Introduction |

This package contains an implementation of the W3C XML Schema Language, a recommendation of the Worldwide Web Consortium available in three parts: XML Schema: Primer and XML Schema: Structures and XML Schema: Datatypes. We consider this implementation complete except for the limitations cited below.

We would very much appreciate feedback on the package via the Xerces-C++ mailing lists, and we encourage the submission of bugs as described on the Bug Reporting page. Please read this document before using this package.

| Limitations |

- Due to the way in which the parser constructs content models for elements with complex content, specifying large values for the `minOccurs` or `maxOccurs` attributes may cause a stack overflow or very poor performance in the parser. Large values for `minOccurs` should be avoided, and `unbounded` should be used instead of a large value for `maxOccurs`.
- The parser treats local elements in the same scope with the same name and namespace as one element declaration and does not differentiate between them.

| Interpretation of Areas that are Unclear or Implementation-Dependent |

| keyref |

| We have interpreted the specs as requiring <keyref> Identity Constraints to refer to <key> or <unique> identity constraints within the scope of the elements to which the <keyref> is attached. This interpretation is at variance with the Schema Primer, which contains an example with a <keyref> declared on an element used inside the element of its corresponding <key>.

| out-of-bound float values |

For float data, the specs does not explicitly specify how to deal with out-of-bound data. Xerces converts these values as below (the values depend on the system specific values of FLT_MAX and FLT_MIN):

Values in range | Values converted
less than -FLT_MAX (approx -3.402823466e+38) | -INF
greater than -FLT_MIN (approx -1.175494351e-38) and less than -0 | -0
greater than +0 and less than +FL_MIN (approx +1.175494351e-38) | +0
greater than +FLT_MAX (approx 3.402823466e+38) | +INF

The effect of this conversion would invalidate an instance data, for example, "1.1e-39", of a data type derived from float, with minExclusive value '+0', since "1.1e-39" is converted to "+0", which is the same as the minExclusive.

| out-of-bound double values |

Similarly, Xerces converts double values as below (the values depend on the system specific values of DBL_MAX and DBL_MIN):

Values in range | Values converted
less than -DBL_MAX (approx -1.7976931348623158e+308) | -INF
greater than -DBL_MIN (approx -2.2250738585072014e-308) and less than -0 | -0
greater than +0 and less than +DBL_MIN (approx +2.2250738585072014e-308) | +0
greater than +DBL_MAX (approx +1.7976931348623158e+308) | +INF

| Usage |

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.

    // Instantiate the DOM parser.
    DOMParser parser;
    parser.setDoNamespaces(true);
    parser.setDoSchema(true);
    parser.parse(xmlFile);

Usage in SAXParser is similar, please refer to the sample program 'samples/SAXCount/SAXCount.cpp' for further reference.

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.

    SAX2XMLReader* parser = XMLReaderFactory::createXMLReader();
    parser->setFeature(XMLUni::fgSAX2CoreNameSpaces, true);
    parser->setFeature(XMLUni::fgXercesSchema, true);
    parser->parse(xmlFile);

Review the sample file, 'samples/data/personal-schema.xml' and 'samples/data/personal.xsd' for an example of an XML Schema grammar.

| Associating Schema Grammar with instance document |

Schema grammars can be associated with instance documents in two ways.

| Specifying Schema Grammar through method calls: |

An application developer may associate schemas with instance documents through methods `setExternalSchemaLocation` if they use namespaces, and `setExternalNoNamespaceSchemaLocation` otherwise. (For SAX2XMLReader, use the properties: "http://apache.org/xml/properties/schema/external-schemaLocation" and "http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation")

Here is an example with no target namespace:

    // 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<XMLCh> janValue(propertyValue);

    parser->setProperty(
           XMLUni::fgXercesSchemaExternalNoNameSpaceSchemaLocation,
           propertyValue);
    parser.parse("test.xml");

Here is an example with a target namespace. Note that it is an error to specify a different namespace in `setExternalSchemaLocation` than the target namespace defined in the Schema.

    // 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<XMLCh> janValue(propertyValue);

    parser->setProperty(
           XMLCh XMLUni::fgXercesSchemaExternalSchemaLocation,
           propertyValue);
    parser.parse("test.xml");

| Specifying Schema Grammar through attributes in the instance document: |

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.

Here is an example with no target namespace:

    <?xml version="1.0" encoding="UTF-8"?>
    <personnel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	   xsi:noNamespaceSchemaLocation='personal.xsd'>
    ...
    </personnel>

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.

    <?xml version="1.0" encoding="UTF-8"?>
    <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">
    ...
    </personnel>

Copyright © 1999-2007 The Apache Software Foundation. All Rights Reserved.