Danno's Annotea protocol requests

This is a brief summary of the Annotea protocol. For more details, please refer to this document. (But note that that document does not have the standing of a W3C standard or even a W3C draft standard. It is simply a working document that various people have chosen to use as the basis for various annotation clients and servers.)

The table above assumes that Danno have been configured with the default container name, and so on. Annotation and Reply <uri>'s are of the form:

  http://<hostname>:/danno/annotea/<annotation-id>
  http://<hostname>:/danno/annotea/<reply-id>
  http://<hostname>:/danno/annotea/body/<body-id>

The <id>s are strings of 16 hexadecimal digits that are generated by the Danno server and returned in the responses to the POST requests.

Danno-specific interpretations

The Annotea protocol document does not define schemas for Annotations, Replies or Bodies, but instead references some RDFS files on the W3C website. These RDFS are rather short on detail. For example, no attempt is made to specify the cardinality of the respective properties. We have therefore made the following "interpretations" of the Annotea documentation and related schemas.

• Every Annotation must have at least one 'a:annotates' property. The property must be URI-valued.
• Every Reply must have exactly one 'tr:' property. The property must be URI-valued.
• An Annotation or Reply may have at most one each of 'dc:date', 'dc:creator', 'dc:title', 'a:created', one 'a:modified'. The 'dc:date', 'a:created' and 'a:modified' properties (if supplied) must be well-formed XML 'dateTime' values.
• An Annotation or Reply may have at most one 'a:body' property which may conform to the HTTP Message schema.
• An Annotation may have have any number of 'a:context' properties. The encoding and meaning of a context property is annotation tool specific, though Dannotate takes it to be an XPointer.
• An Annotation, Reply or Body may contain any other properties, including blank-nodes.
• All Dublin Core (DC) properties use the DC 1.1 versions of the property URIs. DC 1.0 URIs are automatically translated to their DC 1.1 equivalents on input. (This is implemented by the Danno Spring wiring files.)

Danno-specific extensions

Danno implements the following extensions to the basic Annotea model as set out in the protocol document:

• When an Annotation, Reply or Body includes blank-nodes, the extent of the object is deemed to be the blank-node closure, subject to the "max closure depth" limitation in the Danno configuration properties.
• Danno automatically adds or updates the 'a:created', 'a:modified' and 'dc:date' date/timestamps to reflect the actual creation and modification times. This is controlled by Danno configuration properties.

Danno implements a number of extension to the Annotea query syntax. Annotea defines two query parameters ("w3c_annotates" and "w3c_replyTree") that can select targeted sets of Annotations and Replies as required to implement an web annotation tool. These parameters can be combined in a request, with the effect of OR'ing the object result-sets.

Danno's query extensions fall into three categories:

• Danno adds two more "primary" queries ("danno_allObjects" and "danno_allAnnoteaObjects") that allow a client to select objects for the initial result-set from a broader pool.
• Danno adds a number of "restrictions", that serve to eliminate unwanted objects from the results. For example, adding the restriction parameter "danno_creator=Fred" will eliminate all objects that do not have a 'dc:creator' property with value "Fred".
• Finally, Danno adds a couple of "modifier" parameters.

Before processing, the "primary" query parameters are extracted and counted. There must be at least one primary query, and the count must not exceed a configurable maximum (by default 2).

The query is then evaluated in a way that is equivalent to the following:

1. Find all objects that satisfy at least one of the primary queries.
2. Eliminate any objects that do not satisfy all of the restrictions.
3. In 'danno_includeBodies' is given, add any embedded Body objects for any remaining Annotation or Reply objects in the result-set.
4. Return as RDF/XML, with an optional stylesheet processing directive.

(In reality, the SPARQL queries are organized a little differently to what the recipe above suggests, but the end result is the same.)

Here are a couple of example queries. (The URLs have been line-wrapped for the sake of readability.

   http://example.com/danno/annotea/
       ?w3c_annotates=http%3A%2F%2Fwww.w3.org%2F
       &danno_creator=Fred 

This query requests Annotations for the W3 Consortium's website front page that have been created by someone who goes by the name of "Fred".

   http://example.com/danno/annotea/
       ?danno_allAnnoteaObjects
       &danno_annotatesRegex=http%3A%2F%2Fwww%5C.w3%5C.org%2F.%2A

When you unpick the %XX encoding, this query requests all Annotations for resources whose URIs match the regex "http://www\.w3\.org/\.*". In other words, all Annotations for the entire W3 Consortium website.

The complete set of Danno query parameters is as follows:

Dannotate Actions

The Dannotate protocol consists of a number of "actions", each with their own set of parameters. The responses for the actions are variously formatted as HTML, JSON or plain text. (The Dannotate client-side does not see the RDF/XML format used in the Annotea protocol.)

Dannotate Sequences

One way to understand the Dannotate actions is to see them in the context of the client-server interactions. (Aside: this would be a good place to use some UML sequence diagrams.)

Dannotate Request Parameters

The parameters for the Dannotate actions are as follows: