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 to be complete except for the limitations cited below. The implementation has been extensively tested and known problem areas are set out below. In this document we also discuss our interpretation of the specifications where it seems to us particularly likely that others might arrive at a different interpretation. We would very much appreciate feedback on the package via theXerces-J mailing list, and we encourage the submission of bugs as described in the FAQ. Please read this document before using this package.

• No interface is provided for exposing the post-schema validation infoset , beyond that provided by DOM or SAX;
• The parser permits situations in which there is circular importing; that is, where there is a series of schemas which contain <import> information items whose effect is recursive. 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 schema B which also imports schema A, and an instance document validates against schema A, then any reference in schema b to an information item from schema A will produce an error. Circular <include>s have similar limitations.
• length, minLength, and maxLength facets are limited to the value 2147483647. Items larger than this limit will not be validated correctly.
• year and seconds values in date/time datatypes are limited to the value 2147483647. Items larger than this limit will not be validated correctly.
• 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 the parser to throw a StackOverflowError. Large values for minOccurs should be avoided, and unbounded should be used instead of a large value for maxOccurs.

• Due to changes in the specification for Decimals in JDK1.3, not all decimals that should be invalid according to the Schema specs may be found by the parser;

• QName: the specification does not define the unit of length. We chose to implement the length facet as being in units of XML characters in the value space ( # of chars in namespace URI + ":" + local part );
• 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>;

The parsers contained in this package are able to read and validate XML documents with the grammar specified in either DTD or XML Schema format. The schema is specified by the xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute on the root element of the document. The xsi prefix must be bound to the Schema document instance namespace, as specified by the Recommendation. See the sample provided in the Usage section.

In this release, schema validation has been integrated with the regular SAXParser and DOMParser classes. No special classes are required to parse documents that use a schema.

Schema grammars can be associated with instance documents in two ways. An application developer may use the http://apache.org/xml/properties/schema/external-schemaLocation and the http://apache.org/xml/properties/schema/external-noNamespaceSchemaLocation properties to associate schemas with namespaces appearing in instance documents; see the "properties" section of this documentation for details. If this property is not set, then each 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 an xsi:noNamespaceSchemaLocation attribute otherwise. These are usually placed on the root / top-level element in the document, though they may occur on any element; for more details see XML Schema Part 1 section 4.3.2. Here is an example with no target namespace:

	<document xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation='document.xsd'> ... </document>

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.

	<document xmlns='http://my.com' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:schemaLocation='http://my.com document.xsd'> ... </document>

Review the sample file, 'data/personal.xsd' for an example of an XML Schema grammar.