Re: [spec-reviews] Review Web Annotations specs (#93)

Some initial notes:

* 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.
* Likewise, it's very MUST/SHOULD heavy; when specs overuse the RFC2119 terms, it doesn't help readability or interoperability.
* "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.
* 5. 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 payload.

---
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/spec-reviews/issues/93#issuecomment-156889627