How to write a new contract

1. The new WADL contract

The latest specification of WADL permits to include a <doc> child to any element. This is particularly interesting for us since it makes the use of two different files to describe the observers (the contract) unnecessary. Consequently, contract between an observer and UniCORN has been simplified to use just one WADL file including informations of the RDF file (To learn more see  WADL specification).

This document explains how to write the new contract (with required nodes) which is comprehensible by UniCORN.

2. Metadata in <resource> node

We use <doc> node to write metadata.
A standard <doc> node has to be written like this : <doc title="nameOfTheInfo">valueOfTheInfo</doc>
You can give informations in different languages. For that, you have to use xml:lang attribute : <doc xml:lang="myLang" title="nameOfTheInfo">valueOfTheInfo</doc>

Some information are required :

• name : name of the observer.
• description : description of the observer.
• help : url where we can found documentation about the observer.
• mimetype : mimetype tolerated by the observer.
• provider : provider of the contract.
• paramLang : name of the lang parameter if exists. The lang parameter permits to the observer to know in which language user wants tu receive response
• reference : reference of the observer.

Example :

<?xml version="1.0" encoding="utf-8"?>
<application 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://research.sun.com/wadl/2006/10 wadl.xsd" 
        xmlns="http://research.sun.com/wadl/2006/10"
        xmlns:xs="http://www.w3.org/2001/XMLSchema">
        <grammars/>

        <resources base="http://qa-dev.w3.org/wmvs/HEAD/">
                <resource path="check">
                
                        <doc xml:lang="en" title="name">Markup Validator</doc>
                        <doc xml:lang="fr" title="name">Validateur de balises</doc>
                        
                        <doc xml:lang="en" title="description">An observer which validates (X)HTML.</doc>
                        <doc xml:lang="fr" title="description">Un observateur qui valide le (X)HTML.</doc>
                        
                        <doc xml:lang="en" title="help">http://www.w3.org/Unicorn/markup-observer/help</doc>
                        <doc xml:lang="fr" title="help">http://www.w3.org/Unicorn/markup-observer/help_fr</doc>
                        
                        <doc title="mimetype">text/html</doc>
                        <doc title="mimetype">application/xhtml+xml</doc>
                        <doc title="mimetype">image/svg+xml</doc>
                        <doc title="mimetype">application/mathml+xml</doc>
                        <doc title="mimetype">application/smil+xml</doc>
                        
                        <doc xml:lang="en" title="provider">W3C</doc>
                        <doc xml:lang="fr" title="provider">Le W3C</doc>
                        
                        <doc title="paramLang"></doc>
                        
                        <doc title="reference">markup-validator</doc>

       ...

3. Add a method

Inside <method> node, two <doc childs are required :

• inputMethod : possible values are URI, UPLOAD, DIRECT.
• inputParamName : name of the input parameter name.

In the new WADL specification, <query_variable> node is replaced by <param> with two required attributes, name and style. Possible values of the parameter have to be defined in <option> node : <option value="myValue"/>.

Example :

<method name="GET" id="MarkupValidationUri">
   <doc title="inputMethod">URI</doc>
   <doc title="inputParamName">url</doc>
   <request>
      <param name="url" type="xs:anyURI" style="plain"/>
      <param name="charset" default="utf-8" style="plain">
         <option value="utf-8"/>
         <option value="utf-16"/>
      </param>
   </request>
</method>