Comments on the draft W3C Annotatea specification

These comments are based on the draft specification on the W3C 
website at:
http://www.w3.org/2002/12/AnnoteaProtocol-20021219

[There is a more recent draft on the www.annotea.org website at:
http://www.annotea.org/Annotea/User/AnnoteaProtocol-20051226.html
which includes a whole new section on Bookmarks and Topics.  However, I
don't believe it has any official standing.  If it does ... or
should ... have standing, then it would be a good idea if someone at the
W3C added it to the W3C website!!]

0)  The structure and language of the current draft is not really
appropriate as a specification. This is understandable given the history
of the document, but it would need to be addressed if Annotea is to
progress to a W3C recommendation.  (IMO, this work needs to be done
anyway.)

1)  The relationship between the Annotea Protocol and Annotea RDF
schemas should be spelled out more clearly.  I would expect to a
reference in the Annotea Protocol document's overview, and a later
section that lists and describes the core schema properties, and states
whether they are mandatory, recommended, optional, single-valued,
multi-valued, whatever in the context of the protocol.  (I acknowledge
that making properties mandatory goes against the grain with RDF, but an
Annotea client or server-side implementation needs a clear "contract"
which spells out what is required for the protocol to "work".  For
example, the "annotates" property needs to be mandatory in some
contexts.  This is noted in the spec at some points ... but are there
other properties like this?)

2)  Some aspects of the schemas may need to be more tightly specified.
For instance, (IMO) the Annotea Protocol needs to REQUIRE that
'modified' and 'created' properties (if provided) are well-formed XML
dateTime values.  (The Annotea Schema "recommends" use of XML dateTime
syntax, but the examples in the Annotea Protocol document ignore this!!)

3)  The examples in the Annotea Protocol document should probably not
use the 'date' property, as this has no clear meaning.

4)  When POST-ing or PUT-ing an Annotation, a) is the Client allowed to
include arbitrary properties in the RDF, and b) is the Server allowed to
or required to store these properties and return them in subsequent GET
responses?  I think the answers are a) YES and b) ALLOWED not REQUIRED,
but this is not specified.

5)  Which of the listed header fields in the various Annotea requests
and replies are MANDATORY and which ones are just recommended?

6)  When I POST or PUT an annotation with an embedded body, the body is
assigned a URI.  The examples show URLs for the body taking the form
"/Annotations/body/XYZZY", where "/Annotations/XYZZY" was the url for
the annotation.  Is the string "body" required to be present, or could
some other string be used?  Similarly, could the unique part of the body
URI ("XYZZY") be different to the corresponding part of the annotation
URI?

7)  If I PUT or DELETE an annotation that was previously POSTed with an
embedded body, what should happen to the old embedded body?  Bear in
mind that the old body would have been given a URL, and that it could be
the 'object' of some other annotation property.

8)  When I PUT an annotation and the new version leaves out a property
that was present in the old one, should the server delete the property?
I think the answer should be YES, but I don't think that the spec says
this clearly.

9)  If I POST or PUT an annotation containing a non-standard property
whose value is a blank-node, and the Server decides to accept it.
Should the Server assign a URI for the blank-node in the same way that
an embedded body it assigns one for an embedded body?

10)  The "Optimizing query requests" section says that a Server may
refuse to honor a combined request.  What HTTP status code should it set
in the response?  (The Client needs to know this if it is going to retry
the requests individually.)

Finally, here are a couple of areas where I think that the Annotea
Protocol specification needs to be extended:

1) Now that SPARQL is the 'standard' way to express RDF queries, the
Annotea Protocol spec consider specifying how to express SPARQL-based
annotation queries.  (The Algae protocol material could potentially be
deprecated or excised.)

2) Consider extending the Annotea Protocol with mechanism for saying
what annotation properties are required / allowed by a given server.
For instance the Annotea server that I am currently developing will
require a 'context' properties, and may require others.  (I would
envisage defining a bunch of annotation schemas as RDF schemas, and
performing some server-side validation to ensure that annotations
conform with the schemas.)

Received on Tuesday, 11 November 2008 15:24:18 UTC