[Top]

# A RELAX NG Schema for I-X Plans

Like the other definitions, the RELAX NG schema was produced from the Java class definitions for Plan and related classes (plus a small amount of additional information). A RELAX NG schema can be written as XML, but an equivalent "compact syntax" is also available. Both the XML and compact forms can be used with the Jing validator. Sun's Multi-Schema Validator handles at least the XML form.

A RELAX NG schema can specify different content models for the same element name depending on the value of an attribute. This allows us to give the syntax of the particular constraint types understood by the current I-X Process Panels, something that isn't possible in a DTD or XML Schema. This is not done in the main schema but rather in a separate schema that includes it.

This gives us:

- A schema for I-X plans.
  - Compact syntax as html or text.
  - XML syntax.
- An extension that defines specific syntax for "known" constraint types.
  - Compact syntax as html or text.
  - XML syntax.

The html for the constraint extension in compact syntax includes the plan schema and thus provides the most complete picture of the syntax, complete with an index.

The XSLT stylesheets used to produce the compact syntax text and html are available from pantor.com

## RELAX NG Examples

Here is how the compact-syntax schema gives the I-X syntax for lists of objects:

    \list = element list { object* }

That defines a pattern named "`list`" that stands for an element named "`list`" containing zero or more instances of XML that matches the pattern named "`object`".

Since "`list`" is a RELAX NG keyword, it must be preceded by a backslash when used as an identifier in the compact notation (but not when used as an element name). Hence the "`\list`" on the left-hand side of the definition above.

A list of instances of some more specific class, C, would be described by the pattern

    element list { C* }

because for each class, the schema defines a pattern of the same name.

The syntax for maps is given like this:

    map =
       element map
       {
          element map-entry { element key { object }, element value { object } }*
       }

As examples of the XML syntax for RELAX NG schemas, here are the same definitions for `list` and `map` as they are written in XML:

      <define name="list">
        <element name="list">
          <zeroOrMore>
            <ref name="object" />
          </zeroOrMore>
        </element>
      </define>

      <define name="map">
        <element name="map">
          <zeroOrMore>
            <element name="map-entry">
              <element name="key">
                <ref name="object" />
              </element>
              <element name="value">
                <ref name="object" />
              </element>
            </element>
          </zeroOrMore>
        </element>
      </define>

On the initial page, we described plan objects by listing the field names and corresponding types:

    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

In the RELAX NG compact syntax, that becomes

    plan =
       element plan
       {
          element plan-variable-declarations { element list { plan-variable-declaration* } }?
        & element plan-issues { element list { plan-issue* } }?
        & element plan-issue-refinements { element list { plan-issue-refinement* } }?
        & element plan-nodes { element list { plan-node* } }?
        & element plan-refinements { element list { plan-refinement* } }?
        & element constraints { element list { constrainer* } }?
        & element world-state { element list { pattern-assignment* } }?
        & element annotations { map }?
       }

The question marks indicate optional elements (or attributes). The ampersands join elements that may appear in any order.

Here's an example with attributes.

    issue:
       attribute status: status
       attribute priority: priority
       attribute sender-id: name
       attribute ref: name
       attribute report-back: yes-no
       element pattern: list
       element annotations: map

becomes

    issue =
       element issue
       {
          attribute status { status-value }?,
          attribute priority { priority-value }?,
          attribute senderId { name-value }?,
          attribute ref { name-value }?,
          attribute reportBack { yes-no-value }?,
          (  element pattern { \list }?
           & element annotations { map }? )
       }

## RELAX NG Resources

The RELAX NG specification was developed by the OASIS RELAX NG TC.

- RELAX NG Compact Syntax
- RELAX NG Tutorial
- RELAX NG Specification
- The Design of RELAX NG

Jing is an open source RELAX NG validator written in Java.