docs/limitations-schema.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE s1 SYSTEM 'dtd/document.dtd'>
<s1 title="Schema Implementation Limitations">
	<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 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.
        Please read this document before using this package.
        </p>
	</s2>
	<s2 title="Limitations">
        <ul>
            <li> Length, minLength, and maxLength facets are limited to the value 
            2147483647. Items larger than this limit will not be validated 
            correctly.</li>
            <li> Year and seconds values in date/time datatypes are limited to the 
            value 2147483647. Items larger than this limit will not be validated 
            correctly. </li>
        </ul>
    </s2>
    <s2 title='Problem Areas/Known Bugs'>
        <ul>
            <li> 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;</li>
            <li> When the same schema document is both imported and
            included by the same schema document, only the first one
            takes effect;</li>
            <li> If an imported/included/redefined schema document is
            specified via a relative path, the parser may not
            always succeed in locating the document.  Please implement and register a SAX
            EntityResolver (<code>org.xml.sax.EntityResolver</code>) to customize
            the parser&apos;s behaviour to your situation;</li>
        </ul>
    </s2>
    <s2 title='Interpretation of Areas that are Unclear or
            Implementation-Dependent'>
        <ul>
            <li> 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 );</li>
            <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>
	<s2 title="Other Notes">
        <p> 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.</p>
	</s2>
	<s2 title="Usage">
		<p>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.</p>
                <p>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: </p>
<source>&lt;document
  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
  xsi:noNamespaceSchemaLocation='document.xsd'&gt;
...
&lt;/document&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;document
  xmlns='http://my.com'
  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' 
  xsi:schemaLocation='http://my.com document.xsd'&gt;
...
&lt;/document&gt;</source>
		<p>Review the sample file, 'data/personal.xsd' for an example of an XML 
		Schema grammar.</p>
	</s2>
</s1>