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.
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/".
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 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 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 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.
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.
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.
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.)
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: 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.
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
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.
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
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
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
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
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.
To be written
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.
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
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.