Documentation/Observer/Contract

  1. Contract
    1. Application
    2. Resources
    3. Resource
    4. Method
    5. Request
    6. Param
    7. Option

Contract

The contract describes the communication protocol between an observer and Unicorn. It defines all communication methods with their parameters and values allowed. It uses a subset of  WADL, which is a machine process-able description of such HTTP-based Web applications.

Application

The application element is the root of the WADL file and contains a resources element which acts as a container for the resources. A child resource element describes a single resource provided by the application. For Unicorn there is only one resource: the observer. 

<application 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xsi:schemaLocation="http://research.sun.com/wadl/2006/10 wadl.xsd"
    xmlns="http://research.sun.com/wadl/2006/10">
...
</application>

Resources

The resources element acts as a container for the resources provided by the observer. Its base attribute of type xsd:anyURI provides the base URI for its child resource identifier (Unicorn only allows one such element).

Resource

The resource element describes a single resource provided by the observer. It contains one or several (up to three) method elements to describe the input to the observer and has a path attribute of type xsd:string which is the relative URI of the resource. The resource's base URI is given by its parent's base attribute. The resource element also contains several doc elements giving more information to Unicorn:

  • responseType: usually default. Identifier of the response format.
  • mimetype: can appear several times. List all mime-types this observer supports
  • paramLang: parameter dedicated to language negociation (if applicable). Needs to be the name of a param element
  • paramOutput: parameter determining the output format. Needs to be the name of a param element 
<resources base="http://qa-dev.w3.org:8001/css-validator/"> 
    <resource path="validator"> 
        <doc title="responseType">default</doc>
        
        <doc xml:lang="en" title="name">W3C CSS Validator</doc>
        <doc xml:lang="fr" title="name">W3C Validateur CSS</doc>
                
        <doc title="mimetype">text/css</doc>
        <doc title="mimetype">text/html</doc>
        <doc title="mimetype">application/xhtml+xml</doc>
        <doc title="mimetype">image/svg+xml</doc>
                        
        <doc title="paramLang">lang</doc>
        <doc title="paramOutput">output</doc>
...
    </resources>
</resources>

Note: the use of doc elements is a bit of an abuse of the WADL specification as it is used to provide more information to Unicorn. That will probably change in a future version of Unicorn.

Method

A method element describes the input of a HTTP protocol method that may be applied to a resource. A method element has the following combinations of attributes:

  • name Specifies the HTTP method used (GET or POST).
  • id Specifies the identifier of the method.

Unicorn supports up to three method elements, corresponding to the three input types it supports:

  • by URI. The corresponding name attribute is usually GET
  • by direct input. The corresponding name attribute can be GET or POST
  • by file upload. The corresponding name attribute is POST

A method element has several child elements:

  • one doc element with its title attribute set to inputMethod and which content is one of URI, DIRECT, UPLOAD depending on the Unicorn method it represents
  • one doc element with its title attribute set to inputParamName and which content is the name of one parameter describe in the method's request element. This parameter is the one containing the source URI or content of the document to be checked
  • one request element. Specifies the input to the method as a collection of parameters 
<method name="GET" id="CssValidationUri">
    <doc title="inputMethod">URI</doc>
    <doc title="inputParamName">uri</doc>
...
</method>

Request

A request element describes the input that may be included when applying a HTTP method to a resource. A request element has no attributes and may contains zero or more param elements.

Param

A param element represents a URI query parameter as described in  section 17.13 of  HTML 4.01. The runtime values of query variables are sent as URI query parameters when the HTTP method is invoked. A param element can has some doc children (for documentation and internationalization) and has the following attributes:

  • name Specifies the name of the variable as an xsd:NMTOKEN. Required.
  • required Optionally specifies whether the variable is required to be present or not, defaults to false (not required).
  • fixed Optionnally specifies a fixed value for the variable.

A param element can contain one or more option elements.

Option

A option element represents a value that can take its param parent. It has a value attribute containing the value of the parameter. 

<request>
<param name="uri" type="xs:anyURI" style="plain" required="true" /> 
<param name="warning" style="plain" default="1"> 
    <option value="no"></option>
    <option value="0"></option> 
    <option value="1"></option> 
    <option value="2"></option> 
</param>