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", "anyType", 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.

  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)
        * ENTITY
        * date
        * dateTime, duration (formerly timeInstant, timeDuration)
        * gDay, gMonth, gMonthDay, gYear (formerly recurringDate, month,
          recurringDay, year)
        * gYearMonth
        * language
        * Name, NCName, NMTOKEN, NOTATION, QName, token
        * normalizedString (formerly CDATA)
        * string
        * time.

  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. The "union" of simpleTypes is not supported because of parsing
     difficulties.

  7. In complexType definitions, "mixed" content (which allows character content
     to be interspersed with element contents) is not supported.

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

  9. The "All" group has been implemented in a limited way: it restricts the
     included elements to occur once or none (as specified), but only allows
     them to appear in the order in which they are defined.
     XML Schema specifies that the elements can appear (at most once) **in any
     order** within an "All" group.


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. 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.

  5. Element groups are converted to classes with a name constructed by
     appending "Group" to the corresponding group name.  Element "choices" and
     "sequences" (only if it appears under a "choice" group or has "maxOccurs"
     greater than 1) are also converted to classes with names like "choice_1",
     "choice_2", "seq_1" etc.).  No named type is allowed to have such a name
     **unless it appears before the corresponding group definition in the
     schema**.

  6. 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.


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:nil" attribute, whenever present, must be the **last**
          attribute for the element; and
        * the "xsi:type" attribute, whenever present, must be the **last**
          attribute (except for "xsi:nil") for the element.
        In other words, if both "xsi:nil" and "xsi:type" are to be specified
        for a certain element in the instance document, then specify "xsi:nil"
        as the last attribute and the "xsi:type" attribute just before it.

  3. For XML instance documents, there is no implementation to accept the
     short-hand syntax that is used for representing empty contents of elements.
     The content in the instance may be empty because it has only attributes or
     the content parts are all optional.  Such elements have to be written in
     the expanded format.
     For example, the following will be accepted:
         <price value="19.99"></price>
     but the following will cause a parsing error to be generated:
         <price value="19.99"/>

     *** Please note that the schema definition does not need to have this
         restriction, and either notation can be used as appropriate.