Re: [web-annotation] TAG comments (@mnot)

To summarize more fully:

> "This specification is effectively profiling HTTP by using language 
like "The server must support
> the following HTTP methods on the Annotation Container's URI." It 
should just describe the representations
> and interaction expectations upon resources that use them.""

We have reduced and clarified this as much as possible, following the 
patterns established by the Linked Data Platform specification which 
we build upon.  For example, instead of saying that servers MUST 
support some HTTP interaction pattern, we say that If the server 
wishes to provide a particular feature, then it MUST allow it in a 
particular way.  This results, we believe, in better interoperability 
without creating a profile of HTTP.  We do not say, for example, that 
you MUST NOT allow the use of PUT to create an Annotation, but we do 
say that the server MUST implement POST as a means of creating 
Annotations, if that is a feature it wishes to support.

We focus on the requirements that servers and clients need to rely on 
for interoperability within the domain of Annotations such that 
implementers have a recipe to follow, rather than expecting them to 
read every other specification and try to deduce all of the necessary 
features for themselves.

> "Likewise, it's very MUST/SHOULD heavy; when specs overuse the 
RFC2119 terms, it doesn't help
> readability or interoperability."

We have tried to reduce the number of requirements, while still 
providing a sufficiently documented set of interactions to cover the 
use cases established.  Whether there are too many requirements is 
very subjective -- if there were none, there would be nothing to 
conform to.  We feel that since the version that Mark was likely 
reading ([2]), we have done a good job of reducing the protocol to its
 essential components plus those features that developers have asked 
for further clarity on.

> "When a paging preference is received, instead of returning the 
representation of the
> container, the server must return a response with the status code of
 303 and a
> Location header with the URI for the first page." What if the user 
isn't authorised? What if other
> parts of the request are malformed? What if the resource doesn't 
exist? MUSTs like this are seldom helpful."

The specification has been clarified regarding the success of any 
operation.  The requirements now follow the pattern of "If the 
intended request is able to be successfully processed, then the server
 MUST/SHOULD ..." We agree with Mark that unconditional MUSTs are not 
helpful, as when things go wrong, an implementation cannot follow 

> "Error Conditions creates application-specific semantics for 
standard HTTP status codes. This is an
> anti-pattern; the point of HTTP status codes is that any application
 (including intermediaries) can
> understand them; application-specific semantics belong in the 

We have clarified in response to this comment that the section on 
errors (now section 6) is informative, and the situations are examples
 of when those status codes might be appropriate to use.  We believe 
that all of those examples are accurate according to the HTTP 
specification, and hence we are not overloading them with additional 
application specific semantics.

GitHub Notification of comment by tcole3
Please view or discuss this issue at
 using your GitHub account

Received on Thursday, 30 June 2016 14:49:06 UTC