Response

PageOutline

Table of Contents Response format Root element Message Context Title Description Status List Group

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).

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).

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).

Title

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

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.

List

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

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.