Unicorn

Unicorn Tasks Specification

Presentation

Giving the possibility to choose several observers among a long list, does not seem to be very handy for common users and would often be a loss of time, because for example users could want to check conformance of their document without specifiying which type it is, or do every possible observations on this document.

So, we imagined the concept of task. A task consists in two lists:

• A list of observations, describing all the observations that can be done using this task.
• A list of parameters associated with this task and mapped to several parameters of the observations.

In fact this is a little bit more powerful, because you can include tasks inside the list of observations.

The tasklist will be divided in two files: a simple XML one and a RDF one. These two files will be located in the framework. The XML file will contain important information about the tasks, while the RDF file will contain internationalization information and the interface description. In the first versions, for the sake of productivity, we won't have the RDF file, and we will embed the information it should contain in the XML file.

Specification of the XML file

Schema

The schema of the XML file can be found in the project at resources/schemas/tasklist-schema.xsd.

Tasklist

tasklist is the root element. It can contain one or more task elements.

Task

The task element can contain the following:

• Exactly one conds element
• Exactly one routine element
• Exactly one outputseq element
• Zero or one parameter element
• A mandatory id attribute

Here is a sample task:

<?xml version="1.0" ?>
<tasklist xmlns="http://www.w3.org/unicorn/tasklist"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.w3.org/unicorn/tasklist file:./task.xsd">
       
        <task id="conformance">
                <conds>
                        <cond id="cond1" result="passed" observer="rencardeur" type="xpath">
                                <value>(//doctype eq '-//W3C//DTD XHTML 1.0 Strict//EN')or
                                (//doctype eq '-//W3C//DTD HTML 4.01//EN')
                                </value>
                        </cond>
                        <cond id="cond2" result="fail" observer="dealer" type="mimetype">
                                <value>text/html</value>
                        </cond>
                </conds>
                <routine ref="super-checker">
                        <if test="cond1,cond2">
                                <then>
                                        <exec id="so_known_whatever2" value="markup-validator" type="subtask" >
                                                <param name="foo" observer="markup" value="xpath_trop_cool"/>
                                        </exec>
                                        <exec id="so_known_whatever3" value="css-validator" type="subtask" />
                                </then>
                                <else>
                                        <exec id="so_known_whatever4" value="appc-checker" type="subtask" />
                                </else>
                        </if>
                        <exec id="so_known_whatever0" value="appc-checker" type="subtask"/>
                </routine>
               
                <outputseq>
                        <outputgroup id="1">
                                <tasksort>css-validator</tasksort>
                                <tasksort>markup-validator</tasksort>
                        </outputgroup>
                        <outputgroup id="2">
                                <tasksort>appc-checker</tasksort>
                        </outputgroup>
                </outputseq>
                <parameters>
                        <parameter name="output" type="radio" default="ucn" ui="none">
                                <value name="ucn">
                                        <mapped param="output" observer="appc-checker" value="xml" />
                                        <mapped param="output" observer="css-validator" value="ucn" />
                                       
                                        <mapped param="output" observer="markup-validator" value="ucn" />
                                </value>
                        </parameter>
                        <parameter name="warning" type="radio" default="0" observer="css-validator" ui="none" />
                </parameters>
        </task>
</tasklist>

Routine

It contains :

• a ref attribute to use as an ID for the routine.

The routine element is a container for the main algorithm of the Task. You'll be able to write a conditional algorithm for the different checks using the exec and if elements.

<routine ref="super-checker">
        <if test="cond1,cond2">
                <then>
                        <exec id="so_known_whatever2" value="markup-validator" type="subtask" >
                                <param name="foo" observer="markup" value="xpath_trop_cool"/>
                        </exec>
                        <exec id="so_known_whatever3" value="css-validator" type="subtask" />
                </then>
                <else>
                        <exec id="so_known_whatever4" value="appc-checker" type="subtask" />
                </else>
        </if>
        <exec id="so_known_whatever0" value="appc-checker" type="subtask"/>
</routine>

Conds

The Conds element is a container of one or more cond.

Cond

The Cond element is a condition to respect in order to pass the if that uses that cond. It contains :

• An id attribute to reference the condition. This ID will be used in the if tag to reference this condition.
• A result attribute to check if the condition have to check if the test failed or passed.
  The two possibilites in this attribute are :
  • passed
  • failed
• An observer attribute is used to know on which observer the condition has to be checked.
• A type attribute specifies which type of condition it has to perform.
  Currently two types are implemented :
  • xpath
  • mimetype
• A child tag named value is used to write the condition itself (depends on the type).

<cond id="cond1" result="passed" observer="rencardeur" type="xpath">
        <value>
                (//doctype eq '-//W3C//DTD XHTML 1.0 Strict//EN') or (//doctype eq '-//W3C//DTD HTML 4.01//EN')
        </value>
</cond>
<cond id="cond2" result="fail" observer="dealer" type="mimetype">
        <value>text/html</value>
</cond>

Outputseq

The outputseq element is a container of one or more outputgroup. It represents the output sequence, in order to group results together.

Outputgroup

The outputgroup element is a group which contains :

• A mandatory id attribute to reference the group
• One or more tasksort elements containing the names of the observations to group together as a tag value

<outputseq>
        <outputgroup id="1">
                <tasksort>css-validator</tasksort>
                <tasksort>markup-validator</tasksort>
        </outputgroup>
        <outputgroup id="2">
                 <tasksort>appc-checker</tasksort>
        </outputgroup>
</outputseq>

Exec

An exec element describes an observer to call.

It can contain:

• A mandatory id attribute containing the id of the tag.
• A mandatory value attribute which is the name of the observer to call
• A mandatory type attribute describing whether it's an observer or a subtask.
  The different explicit values are :
  • observer
  • subtask

<exec id="so_known_whatever3" value="css-validator" type="subtask" />

<exec id="so_known_whatever4" value="css-validator" type="observer" />

If tags

An exec element describes an observer to call.

It contains:

• A mandatory test attribute containing the different conditions to apply. You can put several conditions separated by a coma ",", which will be interpreted as an "OR".
• A mandatory then tag which will contain the algorithm to perform (other tests and exec) if the condition succeed.
• A conditional else tag where you'll put the algorithm to perform if the condition fails.

 <if test="cond1,cond2">

Subtask

If several tasks have some observations in common, it can be quite boring to rewrite them. The subtask element is here for that. It is in fact a shortcut to another task. Using it will merge all the observations and parameters of the referred task to the current one, unless inconsistencies are found. So, this uses recursivity.

Infinite loops will be avoided because when we find a fixed point, the inclusion ends. For example, the following code won't produce an infinite loop: after the first inclusion, the task is the same as before (with no observation), so the recursion can end.

<exec id="so_known_whatever4" value="appc-checker" type="subtask" />

Parameters and parameter

A parameters element can contain one or more parameter element.

A parameter element can contain:

• name attribute (required): the shortname of the attribute
• ui attribute (optional): indicates the interface where the parameter appears (simple, advanced (default)). It will be relocalized in the RDF file
• default attribute (optional): contains the default value(s) of the parameter
• type attribute (required): describes the type of parameter:
  • dropdownlist represents a list where exactly one element can be selected.
  • checkboxlist represents a list where several elements can be selected. This is the only type which allows multiple values, and so a list of default values.
  • checkbox represents a parameter that can take a boolean value. Such a parameter can only have two values named checked and unchecked.
  • textarea represents a parameter that has no limitations in its possible values, and can contain a long text.
  • textfield is the same as before, but for smaller texts (shall we limit its length?)
  • radio represents a list where at most one element can be selected.
  It will be relocalized in the RDF file
• observer attribute (optional): if specified, the framework will use the corresponding parameter of the observer. It can save a lot of time and writting.
• A list of longname elements, containing the localized name of the parameter
• A list of value elements

Value

A value element describes a value of a parameter and how it is mapped to observers parameters. For example, let's take this piece of code:

<parameter name="warning" default="0" ui="simple" type="dropdown">
    <value name="0">
        <longname xml:lang="en">None</longname>
        <longname xml:lang="fr">Aucun</longname>
        <mapped param="warning" observer="markup-validator" value="none"/>
        <mapped param="warning" observer="css-validator" value="no"/>
    </value>
</parameter>

In this example, the parameter warning has only one possible value (not very useful, but it's enough for the explanation): 0. This value will be mapped to the value none of the markup-validator's warning parameter and to the value no of the css-validator's warning parameter.

A value element can contain:

• A name attribute (required) that will be used internally
• A list of longname elements
• Zero or more mapped elements, describing each mapping:
  • observer attribute refers to the mapped observer (observer, and not observation).
  • name attribute refers to the mapped parameter
  • value attribute refers to the value of the mapped parameter

RDF File

The RDF file contains all localized information for each task of the framework, and also the description of the interface in an element Task. An example RDF file can be found here. We will use it later, but it's specification is more or less ok.

Task

A Task element contain:

• One reference attribute (required) use to link to a task in xml file.
• Zero or more longName property which contain the localized name of the task.
• Zero or more description property which contain the localized description of the task.
• Zero or more hasParameter property which contain one UIParameter element.

UIParameter

A UIParameter element describe a parameter of his task and it contain:

• Zero or more longName property which contain the localized name of the parameter.