Restrictions in the current implementation
                   ==========================================


Order of items in the schema document:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1. All global elements and attributes must be defined before they are
     referenced in a complexType definition using "ref=...".

  2. All element groups and attribute groups must be defined before they are
     referenced in a complex or simple type definition using "<group ref=..." or
     <attributeGroup ref=...".

  3. All types must be defined before they are referenced as "base" types (to
     indicate type-derivation) in other simple or complex type definitions.


Non-supported XML Schema features:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1. Element and attribute wildcards (using "any" or "anyAttribute") are not
     supported.
     As one of the consequences, types of elements **must** be specified in the
     schema - either by  using an explicit "type" attribute, or by using an
     included anonymous type definition.

     The type "anyType" is allowed only if specified as the **base** type (using
     base="xsd:anyType") in a type-derivation.

  2. Generating validations to check identity-constraint definitions ("key",
     "keyref" and "unique") has not been implemented.

  3. The following XML built-in data types have been represented just as
     strings with no further validation of the content:
        * anyUri (formerly uriReference)
        * base64Binary, hexBinary (formerly only binary)
        * date
        * dateTime, duration (formerly timeInstant, timeDuration)
        * ENTITY
        * gDay, gMonth, gMonthDay, gYear (formerly recurringDate, month,
          recurringDay, year)
        * gYearMonth
        * language
        * Name, NCName, NMTOKEN, NOTATION
        * normalizedString (formerly CDATA)
        * QName
        * string
        * time
        * token.

  4. No validation checks are generated for the following constraining facets
     used in "restriction" of simpleTypes:
        * fractionDigits (formerly scale)
        * pattern
        * period
        * totalDigits (formerly precision)
        * whiteSpace.

  5. The special characters "^A" (Control-A) and "^B" (Control-B) should not be
     present in "enumeration" values, because they have been assigned special
     meanings in this context. The use of these characters may cause unexpected
     results.

  6. No special validation check is generated for elements declared as
     "nillable" in the schema to ensure that their contents are truly empty,
     even if xsi:nil="true" is specified for that element in the instance
     document.  The "xsi:nil" attribute is just filtered out by the preprocessor
     for the instance document.

     For the DemeterJ-generated parser, absence of any content will
     automatically cause the corresponding class-part to be initialized to null.

  7. The "union" of simpleTypes is not supported because of parsing
     difficulties.

  8. The "substitutionGroup" feature for elements is not supported.


Naming items in the schema:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1. The application doesn't distinguish between different namespaces, and hence
     all item names must be unique in their individual domains, **across all
     namespaces used**.  The separate domains are:
        * Global elements,
        * Simple and complex types (including user-defined and built-in),
        * Element groups,  and
        * Attribute groups.
     This means that two items belonging to two different domains as specified
     above can share the same name, but not otherwise.

     Furthermore, locally within a complexType definition, attribute names and
     element names must also not conflict with one another.  They should also
     not conflict with part names in a "base" type (if any).

  2. Since the application doesn't distinguish between different namespaces,
     any complexType derived from an **abstract** complexType cannot have an
     attribute named "type", unless there is at least one "required" attribute
     declared **after** it.
     This is to prevent conflict with the "xsi:type" attribute that must be used
     to indicate the actual concrete type in an XML instance document.
     The "xsi:type" attribute, whenever present in the XML instance document,
     must be the **last** of all attributes (except for the "xsi:nil" attribute)
     for any element belonging to that type.

  3. Type derivations (using "extension" or "restriction") of a "simpleType" is
     implemented by adding an element class-part named "value" to the class
     representing the derived type.  Hence, if the derived type is a complexType
     then it cannot have any user-defined attribute named "value".

  4. In a dataclass corresponding to a complexType that includes an element-
     group (using "<group ref = ..."), a class-part named after the group is
     added.
     So, a complexType locally cannot have any other attribute or element with
     the same name as any element-group it contains.

  5. Anonymous type definitions are converted to classes with a name constructed
     by appending "Type" to the corresponding element name.  No named type is
     allowed to have such a name **unless it appears before the anonymous type
     declaration**.  For example, if an element "sample" has an anonymous type
     definition associated with it, then a named type called "sampleType" is
     allowed only if it appears before the element "sample" in the schema
     definition.

  6. Element groups are converted to classes with a name constructed by
     appending "Group" or "Choice" or "AllGrp" (as the case may be) to the
     corresponding group or type name.  Element "sequences" (if it appears under
     a "choice" group or has "maxOccurs" greater than 1), "choices" and "all"
     groups also result in creation of classes with names like "choice_1",
     "choice_2", "seq_1", "allGrpPart_1",  etc.).
     No named type with such a name should be in the schema **unless it appears
     before the corresponding group definition in the schema**.


Representing inheritance in the schema:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1. Due to parsing issues, inheritance hierarchies in schema definitions are
     flattened in the resultant CD,  i.e. the superclass in the CD does not have
     any "common" part and parts defined in the base type are moved to the
     derived classes.
     The parsing issue results from the fact that the DemeterJ-generated parser
     expects "common" parts to be specified at the end; whereas in XML instance
     documents, the common and specific parts can be intermixed in the following
     order:
        * attribute(s) for the base class,
        * attribute(s) for the derived class,
        * markup (">") to indicate the end of the element's start tag,
        * element(s) for the base class,
        * element(s) for the derived class.

  2. Since Demeter only allows for **abstract** superclasses, inheritance
     relationships involving concrete superclasses are not preserved in the
     resultant CD.  However, the "common" parts in the base class are duplicated
     in the "derived" class, as in the case of abstract "base" types.

  3. Since XML schema does not allow simpleType definitions to be declared
     "abstract", simple type derivations in schema definitions are not mapped to
     inheritance relationships in the CD, because Demeter does not allow
     concrete superclasses.  In the CD, the derived type is represented as
     having the same part as the class corresponding to the "base" type, with
     the necessary restrictions added to represent any constraining facet.


Validation of XML schemas:
~~~~~~~~~~~~~~~~~~~~~~~~~~
  1. The application assumes that input schema documents are valid according to
     current specifications, and does not expect invalid constructs.
     It may also accept some schema documents that are not valid but satisfy an
     extended grammar - this has been done to simplify the class-dictionary used
     in the adaptive program.  Checking the validity of schemas is considered to
     be out of scope of this application.


Syntax in the instance documents:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1. For the root element in an XML instance document, all the namespace
     prefix attributes (the ones with "xmlns" as a namespace-prefix, e.g.
     xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance") must be specified
     first, followed by the schema-location attribute (one of "schemaLocation"
     or "noNamespaceSchemaLocation"), followed by the declared attributes of the
     root element itself.
     Of course, the namespace prefix attributes and the schema-location
     attribute are all optional.  However, if a namespace prefix is used
     anywhere in the instance document (e.g. to spcify the concrete type of an
     element using "xsi:type"), then the namespace-prefix must be declared here.

     Namespace-prefix definitions are not allowed to be defined in any element
     other than the root.

  2. For any element in an XML instance document, the "xsi:type" attribute,
     whenever present, must be the **last** attribute (except for the ignored
     "xsi:nil" attribute) for the element.