Response format

All Unicorn observers must implement a custom XML output to communicate validation messages to Unicorn. You can  download the XML schema file of Unicorn responses on  Unicorn public repository.

On top of this documentation, the development instance of Unicorn provides an  online tutorial that will help you understand Unicorn output schema and a  developer task to test your Unicorn output before your tool is integrated into Unicorn.

Root element

The root element of a Unicorn output is an observationresponse element. It has two required attributes:

• xml:lang - The default language of the messages.
• ref - The URI or the name of the document that was submitted (it will be the default reference of all messages).

<observationresponse xmlns="http://www.w3.org/2009/10/unicorn/observationresponse"
                     xmlns:xml="http://www.w3.org/XML/1998/namespace"
                     xml:lang="en"
                     ref="http://www.example.com">
...
</observationresponse> 

Message

The main element of a response is the message element. It has four attributes:

• type (required) - The message type, can be error, info, or warning.
• ref (optional) - If set, will override the root ref attribute.
• xml:lang (optional) - If set, will override the root xml:lang attribute.
• level (optional) - The severity level of the message, 0 being the most severe (not fully implemented).

<observationresponse xmlns="http://www.w3.org/2009/10/unicorn/observationresponse"
                     xmlns:xml="http://www.w3.org/XML/1998/namespace"
                     xml:lang="en"
                     ref="http://www.example.com">

        <message type="info">…</message>
        <message type="error">…</message>
        <message type="warning">…</message>
        <message type="warning" ref="http://www.example.com/doc.html">…</message>

</observationresponse> 

A message is consisted of, in order:

• (optional) context elements.
• (required) a title element.
• (optional) a description element.

Context

A message can have one or several associated contexts. Context elements inform the user on which part of the document the message is related to. Context content is simple text, except that parts of it can be emphasized in a strong tag. Context elements can have seven optional attributes:

• ref - In some cases it can be useful to override the ref attribute of the message on a context scope. This will for example allow you to group all the contexts where an error occurs in a single message, even if these contexts are from different documents.
• line - Line of the context.
• column - Column of the context.

(the following attributes are valid but not yet implemented)

• line-range - If you have to specify a range of lines instead of a single line use this attribute (type is [0-9]+-[0-9]+).
• column-range - Same for columns.
• position - If it makes sense, you can also explain the position of the context with this simple text attribute.
• offset - The offset of the context in the file (used for binary files).

<message type="error" ref="http://www.example.com/doc1.html">
    <context line="1" column="10"> ...the error happened <strong>here</strong>... </context>
    <context line="2" column="20"> another context in this document </context>
    <context line="1" column="10" ref="http://www.example.com/doc2.html"> This context applies to another document </context>
    <title> An error with multiple contexts </title>
</message>

Title

Every message must have a short title. For convenience the title element can also contain links.

<message type="info">
    <title> Your document is in <a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8</a> </title>
</message>

Description

The description element allows you to add a XHTML Basic 1.0 description of the message. The allowed tags are: address, blockquote, pre, h1, h2, h3, h4, h5, h6, div, p, abbr, acronym, cite, code, em, strong, br, span, a, dt, dl, dd, ol, ul, li, img.

Status

If your output contains only messages, Unicorn will consider that the validation failed if there is at least one error message, that the validation status is undefined otherwise. If the validation was a success you have to explicitly declare it using the status element. This element must be at the very beginning of your document or at the very end depending on what is the most convenient for you.

The status element has two attributes:

• value - The status of the response, can be passed, failed, or undef.
• rating - You can also set a rating on 100 if you want. Up to you to decide wich rating is considered passed or failed.

<status value="passed" rating="80" />

List

The list is a convenient way to set the ref attribute or the group attribute (see Group) of several messages.

<observationresponse xmlns="http://www.w3.org/2009/10/unicorn/observationresponse"
                     xmlns:xml="http://www.w3.org/XML/1998/namespace"
                     xml:lang="en"
                     ref="http://www.example.com">

    <message type="info">…</message>
    <message type="error">…</message>

    <list ref="http://www.example.com/doc.html">
        <message type="warning">…</message>
        <message type="error">…</message>
    </list>

</observationresponse> 

Group

If you just add messages and lists to your output, Unicorn will sort your messages by type (info, error, and warning) and then by referenced document (ref attribute). This may not be the way you want to sort them so Unicorn provides a mechanism to sort messages as you want, the group element. The group element allows you to define custom groups in which you'll assign messages using the group attribute of the message or list element. Groups are just like messages without contexts, they have a mandatory title element and an optional XHTML 1.0 Basic description element.

<group name="group1">
    <title>A group</title>
    <description>
        The group <acronym title="Extensible HyperText Markup Language">XHTML</acronym> description.
    </description>
</group>

<message type="info" group="group1">…</message>

<group name="group2">
    <title>You can define groups anywhere in the output</title>
</group>

<message type="error" group="group2">…</message>

<group name="group3" parent="group2">
    <title>You can also define subgroups with the parent attributes</title>
</group>

<list group="group3">
    <message type="warning">…</message>
    <message type="error">…</message>
</list>