Re: Comments on the draft W3C Annotatea specification

Here are yet more comments:

14)  If a query (e.g. GET ?w3c_annotates=... or GET ?w3c_reply_tree=...)
matches nothing, should the server respond with a 404 status code, or a
200 status code with no content, or a 200 status code and an empty RDF
element.  (It appears that annotea.w3.org does the latter ... and
certain clients assume this is what will happen.)

15)  In general, the Annotea spec should clearly specify what HTTP
response statuses and contents that a client should expect, in normal
and (Annotea related) error cases.  This would cover 14) and related
points.

16)  In a Reply, are the 'root' and 'inReplyTo' properties mandatory?  I
think that the answer should be YES, but this is not clearly stated.

17)  The specification discussion of orphan discussion threads in 3.1
and 3.5 seems to suggest that a server MAY wish to prevent them
happening by blocking certain deletions.  But supposing that the server
doesn't do this, the w3c_reply_tree query (as defined by the spec) will
return a tree with nodes missing.  The spec should make it clear that a
client should expect this, and that a fully functional client UI is
expected to be able to display the orphaned subtrees.

18)  A related issue to 17) is that a server may implement access
control extensions;  e.g. Vannotea allows an annotation or reply to be
tagged with an access control policy.  You could get a situation where a
reply R1 is not visible to user Fred, but R2 which is a reply to R1 is
visible.  If Fred issues a w3c_reply_tree query, the response may show
R2 as orphaned.  This is another reason why a client should be able to
cope with this.  [It might be more sensible to include the R1 reply in
the response with various properties removed.  However, the corporate
access control policies may mandate that all traces of R1 ... including
its identity ... are hidden from Fred.]

19)  In the introduction to section 3, it says the following about
't:root':  "whose value is the URI of the resource naming the start of a
discussion (in this case, the annotation that was first replied to)."
Perhaps I am being pedantic, but that >>could<< be read as allowing the
't:root' property to be the URI of a Reply ... thereby starting "a new
discussion thread" whose subject is the Reply.  IMO, it would be a good
thing for the text of the spec made it clear that this was not allowed;
e.g. by saying that the 't:root' property MUST be the URI of an
annotation.

20)  I couldn't find anything in the Annotea Protocol spec that says
that a reply tree must be a strict tree.  Should a server ensure that
this is the case by testing for cycles, etc in POST / PUT requests?  Are
the 'root' and 'inReplyTo' properties required to be single valued?  If
the server is not required to check these things, is a client expected
to be able to cope with cycles and shared nodes in a response from a
w3c_reply_tree query.  IMO, server should be required to prevent cycles
and shared subtrees, or at least to filter them out of a w3c_reply_tree
response.

Received on Friday, 14 November 2008 01:01:54 UTC