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:

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:

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


Jeff Dalton <J.Dalton@ed.ac.uk>