# I-X XML Syntax

I-X systems understand an XML syntax for representing objects. This page provides an informal overview of the syntax and its semantics, and several formal syntactic descriptions are available:

- A BNF-style description.
- An XML Schema.
- A Relax NG schema.

Of the formal syntax definitions, probably the most readable is the compact syntax Relax NG schema written as html. It contains an index and links that make it easier to find definitions; however, it requires a browser that understands cascading style sheets (css). For more information about that schema, and for the same schema in other forms, see the Relax NG schema page.

Some parts of this document that not yet been written are marked by a sentence in italics.

## Namespaces

The element tags in I-X XML should be in the I-X namespace appropriate for the version of the I-X software being used.

At present, the only such namespace is "`http://www.aiai.ed.ac.uk/project/ix/`".

## Object Syntax

The XML represents objects, and objects may contain fields whose values are also objects. Thus nested elements usually alternate between class and field names:

    <class-1>
       <field-1>
          <class-1-1>
             ...
          </class-1-1>
       </field-1>
       <field-2>
          <class-1-2>
             ...
          </class-1-2>
       </field-2>
       ...
    </class-1>

Exceptions to this rule are:

- Fields that have simple, atomic values are often written as attributes rather than subelements.
- Atomic objects do not have fields.
- Lists and sets do not have field names for their members.
- Maps do not have field names for their map-entries.
- An XML element that should not be interpreted as the I-X representation of an object is written inside a `literal-document` element. `literal-document` is a class-name, but there is no field-name element around the contents, and the element inside the `literal-document` needn't obey any of the I-X syntax rules.

### Class Names

Class names are lower-case with words within the name separated by "-". An exception to this rule is that words that are meant to be all upper-case are given in upper-case. This allows a straightforward transformation in both directions between these names and Java class and field names. For example, the Java class name "`XMLTranslator` maps to "`XML-translator`", while the Java name "`XmlTranslator` maps to "`xml-translator`".

### Atomic Objects

Atomic objects are things such as numbers, strings, and the values of enumeration types. Atomic objects are written as

    <class-name>text</class-name>

where text is the textual representation of an instance of the class named class-name.

Examples:

>     <string>This is a string</string>

>     <symbol>arctan</symbol>

>     <name>issue-1</name>

>     <priority>high</priority>

>     <float>3.75</float>

>     <integer>12</integer>

>     <long>-8192542030985258682</long>

#### Names and Symbols

Names and symbols are essentially short, relatively simple, strings that could reasonably be written as attribute values.

Symbols are most often used as words in patterns. The Symbol class corresponds to the symbol or atom type familiar to Lisp and Prolog programmers.

### Lists and Sets

A list is written as a `list` element containing zero or more elements that are I-X XML representations of objects. For example,

    <list>
      <string>Here is a list</string>
      <list>
        <string>containing</string>
        <integer>1</integer>
        <string>sublist</string>
      </list>
    </list>

Sets are the same as lists, except that the element name is `set` rather than `list`.

### Maps

A map is written as a `map` element containing zero or more `map-entry` elements. Each `map-entry` contains a `key` element and a `value` element, each of which may contain any I-X XML representation of an object.

A map is thus written as

    <map>
      <map-entry>
        <key>OBJECT</key>
        <value>OBJECT</value>
      <map-entry>
      ...
    </map>

where each occurrence of "`OBJECT`" may independently be replaced by the XML for any representable object.

### Embedded XML

A `literal-document` object contains an XML element, and such objects can be used to include XML that should be left as-is rather than being treated as if intended to represent an I-X object.

For example, the following piece of XML

    <test-element xmlns="" test-attrib="attrib-value">
      <test-subelement />
    </test-element>

could be placed in I-X XML (where any object could appear) by writing this:

    <literal-document>
      <test-element xmlns="" test-attrib="atrib-value">
        <test-subelement />
      </test-element>
    </literal-document>

(The main places "where any object could appear" in plans are as the key or value of an annotation.)

## I-X Objects

This section describes the principal objects manipulated by I-X systems: issues, activities, constraints, and annotations.

On this page, we will use a semi-formal notation for describing the syntax of objects:

    class-name:
       attribute-or-element field-name: field-value
       ...

where field-value is one of

- class-name.
- `list of` class-name.

Enumerations will be described as

    class-name: value1 | value2 | ...

The subclasses of an abstract class will be listed in a similar fashion:

    class-name: subclass-name | ...

The notation "`list of` class-name" indicates a list of instances of the named class.

### Patterns

Each issue or activity contains a sentence called, partly for historical reasons, a "pattern".

For an activity, the pattern states what the action would be performed, for example "go from Edinburgh to Glasgow". That activity might have subactivities such as "go to Waverley station" and "buy a ticket". A pattern for an activity should begin with a verb.

For issues, the patterns are meant to be questions, such as "why Glasgow?".

However, patterns are not single strings. Instead, they are lists of objects. Any object that can be represented in I-X XML may appear in a pattern. (Indeed, inside an I-X system even objects that cannot be represented in XML could appear in a pattern.) However, patterns are normally composed of simple atomic objects and, in some cases, subpatterns. Words in patterns are usually represented as symbols or strings. The sentence "go to Glasgow" would be a 3-element list, for example

    <list>
      <symbol>go</symbol>
      <symbol>to</symbol>
      <symbol>Glasgow</symbol>
    </list>

or perhaps

    <list>
      <symbol>go</symbol>
      <symbol>to</symbol>
      <string>Glasgow</string>
    </list>

The "?" at the end of a question would normally not be included in a pattern, and attempting to include it could lead to subtle problems.

Explain variables, matching and `&rest`

### Issues

An issue attaches some information to a pattern.

    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

    status: blank | complete | executing | possible | impossible | n/a

    priority: lowest | low | normal | high | highest

    yes-no: yes | no

The `sender-id`, `ref`, and `report-back` fields are used when an issue is forwarded from one agent to another, for instance when delegating an issue to a subordinate. A `report-back` value "`yes`" indicates that the recipient should send progress reports about its handling of the issue. The reports should be sent to the agent whose name is given as the value of `sender-id`, and the `ref` attribute allows the agent receiving such reports to determine which issue the reports are about.

The forwarding and report-back mechanisms, and the fields they use, are likely to change in the near future.

### Activities

The representation of activities parallels that of issues.

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

### Constraints

We will sometimes need the notion of a `constrainer`. This is because temporal "before" constraints are not yet represented by `constraint` objects; instead, they are represented by instances of a separate class, `ordering`. A more general notion that includes both `constraint` and `ordering` is therefore needed.

    constrainer: constraint | ordering

    constraint:
       attribute type: symbol
       attribute relation: symbol
       attribute sender-id: name
       element parameters: list
       element annotations: map

    ordering:
       element from: node-end-ref
       element to: node-end-ref
       element annotations: map

    node-end-ref:
       attribute end: end
       attribute node: name

    end: begin | end

Explain orderings and some constraint types.

Pattern-assignments appear in the `parameters` list of certain constraints.

    pattern-assignment:
       element pattern: list
       element value: object

### Annotations

Annotations are represented by a map (see above) in which any object that can be represented in I-X XML may appear as a key or value.

## Chat Messages and Reports

    chat-message:
       attribute sender-id: name
       element text: string

    report:
       attribute report-type: report-type
       attribute priority: priority
       attribute sender-id: name
       attribute ref: name
       element text: string
       element annotations: map

    report-type: success | failure | progress | information | event

    priority: lowest | low | normal | high | highest

## Domains

    domain:
       element name: string
       element variable-declarations: list of variable-declaration
       element refinements: list of refinement
       element annotations: map

    variable-declaration:
       attribute name: item-var
       element annotations: map

    refinement:
       element name: string
       element pattern: list
       element variable-declarations: list of variable-declaration
       element nodes: list of node-spec
       element orderings: list of ordering
       element constraints: list of constraint
       element issues: list of issue
       element comments: string
       element annotations: map

    node-spec:
       attribute id: name
       element pattern: list

## Plans

    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

Plans are made from I-X objects of the sorts discussed above together with "structural" objects that show how the I-X objects are related. For example, a `plan-issue` is a structural object that is wrapped around an `issue` and associated with another structural object, a `plan-issue-refinement`, to show how the issue is broken down into subissues. A `plan-node` and a `plan-refinement` perform a similar function for an `activity`.

The structural objects are not of much interest in themselves and are not retained (outside of the plan object) when a plan is loaded into an I-X system. Any annotations on such objects will therefore be lost if a plan is loaded and then the resulting "state" is used to construct a new plan object. (Annotations on issues and activities, on the other hand, will be retained.)

Explain world-state.

### Plan-Variables and Declarations

To be written

### Issues in a Plan

Issues are not included directly in a plan. Instead, each is wrapped in a `plan-issue`.

    plan-issue:
       attribute id: name
       attribute expansion: name
       element issue: issue
       element annotations: map

    plan-issue-refinement:
       attribute id: name
       attribute expands: name
       element plan-variable-declarations: list of plan-variable-declaration
       element plan-issues: list of plan-issue
       element annotations: map

A paired `plan-issue` and `plan-issue-refinement` are used to relate an issue to its subissues.

If an issue, i, has subissues, and is wrapped in `plan-issue` pi, the value of pi's `expansion` attribute should be the id of a `plan-issue-refinement`; and then the value of the `expands` attribute of that `plan-issue-refinement` should be pi's id. i's subissues are the issues inside the plan-issues of that refinement.

For example, if issue-a has subissues issue-a.1 and issue-a.2, they would be placed in a plan as follows:

    <?xml version="1.0" encoding="UTF-8"?>
    <plan xmlns="http://www.aiai.ed.ac.uk/project/ix/">
     <plan-issues>
      <list>
       <plan-issue id="issue-0" expansion="issue-refinement-0">
        <issue>
         <issue> ... XML for issue-a ... </issue>
        </issue>
       </plan-issue>
     </plan-issues>
     <plan-issue-refinements>
      <list>
       <plan-issue-refinement id="issue-refinement-0" expands="issue-0">
        <plan-issues>
         <list>
          <plan-issue id="issue-0-0">
           <issue>
            <issue> ... XML for issue-a.1 ... </issue>
           </issue>
          </plan-issue>
          <plan-issue id="issue-0-1">
           <issue>
            <issue> ... XML for issue-a.2 ... </issue>
           </issue>
          </plan-issue>
         </list>
        </plan-issues>
       </plan-issue-refinement>
      </list>
     </plan-issue-refinements>
     ...
    </plan>

If a subissue has subissues of its own, they are specified by a further plan-issue-refinemement. All of the refinements required by such relationships are held in a single list in the `plan-issue-refinements` field of the plan.

A tree of issues thus has a "flattened" representation in a plan.

Another potentially confusing point is that the XML for a plan-issue will typically have an `issue` tag inside an `issue` tag, like this:

       <plan-issue id="issue-0" expansion="issue-refinement-0">
        <issue>
         <issue> ... XML for issue-a ... </issue>
        </issue>
       </plan-issue>

The outer `issue` tag represents a field in the plan-issue object, while the inner `issue` represents the class of the issue object that is the value of that field. If the value of the field were instead an instance of a subclass of Issue, the inner tag would be based on the name of that subclass instead.

### Activities in a Plan

Like issues, activities are not included directly in a plan. Instead, `plan-node` and `plan-refinement` do for activities what `plan-issue` and `plan-issue-refinement`, respectively, do for for issues.

    plan-node:
       attribute id: name
       attribute expansion: name
       element activity: activity
       element annotations: map

    plan-refinement:
       attribute id: name
       attribute expands: name
       element plan-variable-declarations: list of plan-variable-declaration
       element plan-nodes: list of plan-node
       element constraints: list of constrainer
       element annotations: map

### Constraints in Plan-Refinements

A `plan-refinement`, unlike a `plan-issue-refinement`, may contain constraints; and those constraints may refer to a `plan-node` within the same `plan-refinement` by using the node's id, if the constraint is of a kind that allows such a reference.

Here, as an example, are the relevant parts of a plan with a single top-level activity that has three sequential subactivities. The full plan is also available.

    <?xml version="1.0" encoding="UTF-8"?>
    <plan xmlns="http://www.aiai.ed.ac.uk/project/ix/">
     <plan-nodes>
      <list>
       <plan-node id="node-0" expansion="refinement-0">...</plan-node>
      </list>
     </plan-nodes>
     <plan-refinements>
      <list>
       <plan-refinement id="refinement-0" expands="node-0">
        <plan-nodes>
         <list>
          <plan-node id="node-0-0">...</plan-node>
          <plan-node id="node-0-1">...</plan-node>
          <plan-node id="node-0-2">...</plan-node>
         </list>
        </plan-nodes>
        <constraints>
         <list>
          <ordering>
           <from><node-end-ref end="end" node="node-0-0" /></from>
           <to><node-end-ref end="begin" node="node-0-1" /></to>
          </ordering>
          <ordering>
           <from><node-end-ref end="end" node="node-0-1" /></from>
           <to><node-end-ref end="begin" node="node-0-2" /></to>
          </ordering>
         </list>
        </constraints>
       </plan-refinement>
      </list>
     </plan-refinements>
    </plan>

The `ordering`

      <ordering>
       <from><node-end-ref end="end" node="node-0-1" /></from>
       <to><node-end-ref end="begin" node="node-0-2" /></to>
      </ordering>

says that the activity contained in the `plan-node` with id "`node-0-1`" must end before activity contained in the `plan-node` with id "`node-0-2`" begins.