[Top]

# An XML Schema

The schema was derived from the Java class definitions, plus a small amount of additional information. A BNF-style syntax and a Relax NG schema were produced in a similar way and for many purposes may be easier to read.

The schema gives a syntax for everything that would normally appear. However, it is not possible to give an absolutely complete syntax, because new representable classes might be defined by particular applications or tools, even at run-time. Instances of such classes will be represented in the usual way, as described on the introductory page, but will not be covered by the current schema. The schema will be extended to include any new clases that enter common use.

Moreover, some things cannot be decscribed by an XML schema. While the schema does give the general syntax for a constraint, it cannot describe the way the contents of the `parameters` field vary depending on the values of the `type` and `relation` fields. For that, see the rules for `KNOWN-CONSTRAINT` in the BNF syntax.

## Representing the Class-Subclass Relation

Since fields may be written in any order, `xsd:all` elements are used when defining the XML schema type that describes the contents of an object that has fields written as elements. However, there are restrictions on `xsd:all` that stop is from using subtypes for subclasses.

The schema therefore takes a different and unusual approach. Java's single-inheritance class-subclass relation is handled by substitution groups in the schema. Each class has a substitution group that is in the substitution group of its superclass, and each non-abstract class has a type that lists its complete contents (rather than extending a supertype).

To avoid confusion with the lower-case, class-name element tags used when representing objects in XML, the substitution groups use upper-case names for abstract elements, and there is an upper-case, abstract element for each class, as well as a (concrete), lower-case one. For example, for the class Issue, which we regard as a subclass of Object, the schema defines:

     <xsd:element name="OBJECT" abstract="true" />

     <xsd:element name="ISSUE" abstract="true" substitutionGroup="OBJECT" />

     <xsd:element name="issue" type="issue" substitutionGroup="ISSUE" />

The upper-case elements are abstract and so never appear in documents. Instead, they allow the schema to say that an instance of a class or of one of its subclasses may appear. Thus, `OBJECT` allows `ISSUE`, and `ISSUE` in turn allows `issue`. If there were a subclass of Issue, ExampleIssue, that could appear, it would get the element defintions

     <xsd:element name="EXAMPLE-ISSUE" abstract="true"
                  substitutionGroup="ISSUE" />

     <xsd:element name="example-issue" type="example-issue"
                  substitutionGroup="EXAMPLE-ISSUE" />

The concrete, lower-case elements are always "off to the side", and the main tree structure is given by the abstract, upper-case elements. So if C is a subclass of B, and B is a subclass of A, the screme does not embody those relationships in a type tree like this:

       a
       |
       b
       |
       c

Instead, it uses an element tree:

         A
        / \
       B   a
      / \
     C   b
      \
       c

## What the Schema Defines for a Class

For a class C named "`class`", the schema defines:

- (Implicitly), an upper-case substitution group, `CLASS`.
- An abstract upper-case element, `CLASS`, in the substitution group of C's superclass.
- A concrete lower-case element, `class`, of type `class` and in subsitiution group `CLASS`.
- A type, `CLASS-as-element`, that is a sequence containing one (upper-case) `CLASS` element.
- A lower-case type, `class`, that describes the constants of instances of C.

For abstract classes, the lower-case element and type are omitted.

In addition, if lists of C occur in the syntax of any classes described by the schema, the schema defines:

- A type, `list-of-CLASS-as-element`, that is a sequence contraining one "`list`" element of type `list-of-CLASS`.
- A type, `list-of-CLASS`, that is a sequence of zero or more `CLASS` elements.

Note that this implicitly takes care of list of instances of subclasses of C.

The type `CLASS-as-element` is used when an instance of C, or of one of C's subclasses, must be written as an element with the instance's (lower-case) class name as the tag. `list-of-CLASS` works in a similar way.

The `-as-element` definitions are simply convenient abbreviations for something that would otherwise have to be written out in full each time.

As a result of this definition structure, the concrete "content" types correspond closely to the semi-formal notation used earlier. For example,

    plan:
       element plan-variable-declarations: list of plan-variable-declaration
       element plan-issues: list of plan-issue
       element plan-issue-refinements: list of plan-issue-refinement
       element plan-nodes: list of plan-node
       element plan-refinements: list of plan-refinement
       element constraints: list of constrainer
       element world-state: list of pattern-assignment
       element annotations: map

becomes

     <!--plan-->

     <xsd:element name="PLAN" abstract="true" substitutionGroup="OBJECT" />

     <xsd:element name="plan" type="plan" substitutionGroup="PLAN" />

     <xsd:complexType name="PLAN-as-element">
      <xsd:sequence>
       <xsd:element ref="PLAN" />
      </xsd:sequence>
     </xsd:complexType>

     <xsd:complexType name="plan">
      <xsd:all>
       <xsd:element name="plan-variable-declarations"
                    type="list-of-PLAN-VARIABLE-DECLARATION-as-element"
                    minOccurs="0" />
       <xsd:element name="plan-issues" type="list-of-PLAN-ISSUE-as-element" minOccurs="0" />
       <xsd:element name="plan-issue-refinements"
                    type="list-of-PLAN-ISSUE-REFINEMENT-as-element"
                    minOccurs="0" />
       <xsd:element name="plan-nodes" type="list-of-PLAN-NODE-as-element" minOccurs="0" />
       <xsd:element name="plan-refinements" type="list-of-PLAN-REFINEMENT-as-element" minOccurs="0" />
       <xsd:element name="constraints" type="list-of-CONSTRAINER-as-element" minOccurs="0" />
       <xsd:element name="world-state" type="list-of-PATTERN-ASSIGNMENT-as-element" minOccurs="0" />
       <xsd:element name="annotations" type="MAP-as-element" minOccurs="0" />
      </xsd:all>
     </xsd:complexType>