Please check the insert: <a href="https://www.w3.org/annotation/errata/"> insert: <strong> errata insert: </strong> insert: </a> for any errors or issues reported since publication. insert: </p>
Copyright © 2016 2017 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and document use rules apply.
Annotations are typically used to convey information about a resource or associations between resources. Simple examples include a comment or tag on a single web page or image, or a blog post about a news article.
The Web Annotation Protocol describes the transport mechanisms for creating and managing annotations in a method that is consistent with the Web Architecture and REST best practices.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
The Candidate Recommendation exit criteria are listed in the delete: <a href="#candidate-recommendation-exit-criteria"> appendix delete: </a> . Implementers will find test suites on the delete: <a href="https://github.com/w3c/web-platform-tests/"> Web Platform Tests delete: </a> repository. delete: </p> delete: <p> This document was published by the Web Annotation Working Group as a Candidate Proposed Recommendation. This document is intended to become a W3C Recommendation. If you wish to make The insert: <abbr title="World Wide Web Consortium"> W3C insert: </abbr> Membership and other interested parties are invited to review the document and send comments regarding this document, please send them to delete: <a href="mailto:public-annotation@w3.org"> to insert: <a rel="discussion" href="mailto:public-annotation@w3.org"> public-annotation@w3.org ( subscribe , archives ). delete: <abbr title="World Wide Web Consortium"> W3C delete: </abbr> publishes a ) through 14 February 2017. Advisory Committee Representatives should consult their insert: <a href="https://www.w3.org/2002/09/wbs/myQuestionnaires"> WBS questionnaires insert: </a> . Note that substantive technical comments were expected during the Candidate Recommendation to indicate review period that the document is believed to be stable and to encourage implementation by the developer community. This Candidate Recommendation is expected to advance to Proposed Recommendation no earlier than ended 30 September 2016. All comments are welcome.
Please see the Working Group's implementation report .
Publication as a Candidate Proposed Recommendation does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is governed by the 1 September 2015 W3C Process Document .
This section is non-normative.
Interoperability between systems has two basic aspects: the syntax and semantics of the data that is moved between the systems, and the transport mechanism for that movement. The HTTP protocol and the Web architecture provides us with a great starting point for a standardized transport layer, and can be used to move content between systems easily and effectively. Building upon these foundations allows us to make use of existing technology and patterns to ensure consistency and ease of development.
The Web Annotation Protocol describes a transport mechanism for creating, managing, and retrieving Annotations. Annotations in this specification are assumed to follow the requirements of the Web Annotation Data Model [ delete: <a href="#bib-annotation-model" class="bibref"> insert: <a class="bibref" href="#bib-annotation-model"> annotation-model ] and Web Annotation Vocabulary [ delete: <a href="#bib-annotation-vocab" class="bibref"> insert: <a class="bibref" href="#bib-annotation-vocab"> annotation-vocab ]. This specification builds upon REST principles and the Linked Data Platform [ delete: <a href="#bib-ldp" class="bibref"> insert: <a class="bibref" href="#bib-ldp"> ldp ] recommendation, and familiarity with it is recommended.
delete: <section property="bibo:hasPart" resource="#aims-of-the-protocol" typeof="bibo:Chapter" id="aims-of-the-protocol"> delete: <h3 resource="#h-aims-of-the-protocol" id="h-aims-of-the-protocol"> insert: <section id="aims-of-the-protocol" typeof="bibo:Chapter" resource="#aims-of-the-protocol" property="bibo:hasPart">The primary aim of the Web Annotation Protocol is to provide a standard set of interactions that allow annotation clients and servers to interoperate seamlessly. By being able to discover annotation protocol end-points and how to interact with them, clients can be configured either automatically or by the user to store annotations in any compatible remote system, rather than being locked in to a single client and server pair.
For those familiar with the Web Annotation model, LDP, and REST, much of the Annotation Protocol will be very obvious. The following aspects are the most important new requirements.
application/ld+json;profile="http://www.w3.org/ns/anno.jsonld"
ldp:constrainedBy
URL is http://www.w3.org/TR/annotation-protocol/
rel
type of: http://www.w3.org/ns/oa#annotationService
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY , MUST , MUST NOT , RECOMMENDED , SHOULD , and SHOULD NOT are to be interpreted as described in [ delete: <a href="#bib-RFC2119" class="bibref"> insert: <a class="bibref" href="#bib-RFC2119"> RFC2119 ].
The Web Annotation Protocol is defined using the following basic principles:
The Annotation Server delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST support the following HTTP methods on the Annotation's IRI:
GET
(retrieve the description of the Annotation), HEAD
(retrieve the headers of the Annotation without an entity-body), OPTIONS
(enable CORS pre-flight requests [ delete: <a href="#bib-cors" class="bibref"> insert: <a class="bibref" href="#bib-cors"> cors ]). Servers delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD use HTTPS rather than HTTP for all interactions, including retrieval of Annotations.
Servers delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST support the JSON-LD representation using the Web Annotation profile. These responses delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST have a Content-Type
header with the application/ld+json
media type, and it delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD have the Web Annotation profile IRI of http://www.w3.org/ns/anno.jsonld
in the profile
parameter.
Servers delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD support a Turtle representation, and delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY support other formats. If more than one representation of the Annotation is available, then the server delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD support content negotiation. Content negotiation for different serializations is performed by including the desired media type in the HTTP Accept
header of the request, however clients cannot assume that the server will honor their preferences [ delete: <a href="#bib-rfc7231" class="bibref"> insert: <a class="bibref" href="#bib-rfc7231"> rfc7231 ].
Servers delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY support different JSON-LD profiles. Content negotiation for different JSON-LD profiles is performed by adding a profile
parameter to the JSON-LD media type in a space separated, quoted list as part of the Accept
header.
Servers delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD use the 200 HTTP status code when no errors occurred while processing the request to retrieve an Annotation, and delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY use 3XX HTTP status codes to redirect to a new location.
The response from the Annotation Server delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST have a Link
header entry where the target IRI is http://www.w3.org/ns/ldp#Resource
and the rel
parameter value is type
. The Annotation type of http://www.w3.org/ns/oa#Annotation
delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY also be added with the same rel
type. This is to let client systems know that the retrieved representation is a Resource and an Annotation, even if the client cannot process the representation's format.
The For HEAD and GET requests, the response delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST have an ETag
header with an entity reference value that implements the notion of entity tags from HTTP [ delete: <a href="#bib-rfc7232" class="bibref"> insert: <a class="bibref" href="#bib-rfc7232"> rfc7232 ]. This value will be used by the client when sending update or delete requests.
The response delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST have an Allow
header that lists the HTTP methods available for interacting with the Annotation [ delete: <a href="#bib-rfc7231" class="bibref"> insert: <a class="bibref" href="#bib-rfc7231"> rfc7231 ].
If For HEAD and GET requests, if the server supports content negotiation by format or JSON-LD profile, the response delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST have a Vary
header with Accept
in the value [ delete: <a href="#bib-rfc7231" class="bibref"> insert: <a class="bibref" href="#bib-rfc7231"> rfc7231 ]. This is to ensure that caches understand that the representation changes based on the value of that request header.
GET /annotations/anno1 HTTP/1.1 Host : example.org Accept : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
HTTP/1.1 200 OK Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Link : <http://www.w3.org/ns/ldp#Resource>; rel="type" ETag : "_87e52ce126126" Allow : PUT,GET,OPTIONS,HEAD,DELETE,PATCH Vary : Accept Content-Length : 287 delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : "http://www.w3.org/ns/anno.jsonld" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "created" : "2015-01-31T12:03:45Z" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "TextualBody" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "value" : "I like this page!" }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://www.example.com/index.html" }
If the Annotation Server supports the management of Annotations, including one or more of creating, updating, and deleting them, then the following section's requirements apply. The Annotation Protocol is a use of the Linked Data Platform [ delete: <a href="#bib-ldp" class="bibref"> insert: <a class="bibref" href="#bib-ldp"> ldp ] specification, with some additional constraints derived from the Web Annotation Data Model [ delete: <a href="#bib-annotation-model" class="bibref"> insert: <a class="bibref" href="#bib-annotation-model"> annotation-model ].
An Annotation Server delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST provide one or more Containers within which Annotations can be managed: an Annotation Container. An Annotation Container is at the same time both a Container [ delete: <a href="#bib-ldp" class="bibref"> insert: <a class="bibref" href="#bib-ldp"> ldp ] (a service for managing Annotations) and an OrderedCollection [ delete: <a href="#bib-activitystreams-core" class="bibref"> insert: <a class="bibref" href="#bib-activitystreams-core"> activitystreams-core ] (an ordered list of Annotations). It can have descriptive and technical information associated with it to allow clients to present it to a user in order to allow her to decide if it should be used or not. The classes, properties and representations for the Collection model are described in the Web Annotation Data Model, and the mappings to Activity Streams provided in the Web Annotation Vocabulary [ insert: <cite> insert: <a class="bibref" href="#bib-annotation-vocab"> annotation-vocab insert: </a> insert: </cite> ].
Annotation Containers delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD implement the LDP Basic Container specification, but delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY instead implement another type of Container, such as a Direct or Indirect Container, to fulfill business needs. Annotation Containers delete: <em title="MAY" class="rfc2119"> MAY The URI of an Annotation Container insert: <em class="rfc2119" title="MUST NOT"> MUST NOT have any IRI, but it delete: <em title="MUST" class="rfc2119"> a query or fragment component, and the path component insert: <em class="rfc2119" title="MUST"> MUST end in a "/"
character.
Implementations delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD use HTTPS rather than HTTP for all interactions with Annotation Containers.
The creation, management, and structure of Annotation Containers are beyond the scope of this specification. Please see the Linked Data Platform specification [ delete: <a href="#bib-ldp" class="bibref"> insert: <a class="bibref" href="#bib-ldp"> ldp ] for additional information.
delete: <section property="bibo:hasPart" resource="#container-retrieval" typeof="bibo:Chapter" id="container-retrieval"> delete: <h3 resource="#h-container-retrieval" id="h-container-retrieval"> insert: <section id="container-retrieval" typeof="bibo:Chapter" resource="#container-retrieval" property="bibo:hasPart">The Annotation Server delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST support the following HTTP methods on the Annotation Container's IRI:
GET
(retrieve the description of the Container and the list of its contents, described below), HEAD
(retrieve the headers of the Container without an entity-body), OPTIONS
(enable CORS pre-flight requests [ delete: <a href="#bib-cors" class="bibref"> insert: <a class="bibref" href="#bib-cors"> cors ]). When an HTTP GET request is issued against the Annotation Container, the server delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST return a description of the container. That description delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST be available in JSON-LD, delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD be available in Turtle, and delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY be available in other formats. The JSON-LD serialization of the Container's description delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD use both the LDP context ( http://www.w3c.org/ns/ldp.jsonld
), and the Web Annotation's profile and context [ delete: <a href="#bib-annotation-model" class="bibref"> insert: <a class="bibref" href="#bib-annotation-model"> annotation-model ], unless the request would determine otherwise.
Servers delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD use the 200 HTTP status code if the request is successfully completed without errors and does not require redirection based on the client's preferences.
All supported methods for interacting with the Annotation Container delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD be advertised in the Allow
header of the GET
, HEAD
and OPTIONS
responses from the container's IRI . The Allow
header delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY also be included on any other responses.
Annotation Containers delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST return a Link
header [ delete: <a href="#bib-rfc5988" class="bibref"> insert: <a class="bibref" href="#bib-rfc5988"> rfc5988 ] on all responses with the following components:
rel
parameter value is type
and the target IRI is the appropriate Container Type, such as http://www.w3.org/ns/ldp#BasicContainer
for Basic Containers. http://www.w3.org/TR/annotation-protocol/
, and the rel
parameter value is the IRI http://www.w3.org/ns/ldp#constrainedBy
.
All HTTP For HEAD and GET requests, responses from Annotation Containers delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST include an ETag
header that implements the notion of entity tags from HTTP [ delete: <a href="#bib-rfc7230" class="bibref"> rfc7230 insert: <a class="bibref" href="#bib-rfc7232"> rfc7232 ]. This value will insert: <em class="rfc2119" title="SHOULD"> SHOULD insert: </em> be used by administrative clients when updating the container by including it in an If-Match
request header in the same way as clients wanting to update an Annotation.
If the Accept
header is absent from the a GET request, then Annotation Servers delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST respond with a JSON-LD representation of the Annotation Container, however clients with a preference for JSON-LD delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD explicitly request it using an Accept
request header.
If the server supports content negotiation by format or JSON-LD profile, the response to a HEAD or GET request from the Annotation Container delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST have a Vary
header that includes Accept
in the value to ensure that caches can determine that the representation will change based on the value of this header in requests.
Responses from Annotation Containers that support the use of the POST method to create Annotations delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD include an Accept-Post
header on responses to GET, HEAD and OPTIONS requests. The value is a comma separated list of media-types that are acceptable for the client to send via POST [ delete: <a href="#bib-ldp" class="bibref"> insert: <a class="bibref" href="#bib-ldp"> ldp ].
Link : <http://www.w3.org/ns/ldp#BasicContainer>; rel="type" Link : <http://www.w3.org/TR/annotation-protocol/>; rel="http://www.w3.org/ns/ldp#constrainedBy" ETag : "0f6b5cd8dc1f754a1738a53b1da34f6b" Vary : Accept Allow : POST, GET, OPTIONS, HEAD Accept-Post : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld", text/turtle
As there are likely to be many Annotations in a single Container, the Annotation Protocol adopts the ActivityStreams collection paging mechanism for returning the contents of the Container. Each page Collection Page contains an ordered list with a subset of the managed Annotations, such that if every page is traversed, a client can reconstruct the complete, ordered contents of the container. container/collection. The number of IRIs or Annotation descriptions included on each page is at the server's discretion, and may be inconsistent between pages. The feature or features by which the Annotations are sorted are not explicit in the response.
The requirements for JSON-LD representation of Annotation Collections are defined in the Web Annotation Data Model, and are summarized here. insert: </p>
insert: <p> The Collection insert: <em class="rfc2119" title="MUST"> MUST insert: </em> have an IRI that identifies it, and insert: <em class="rfc2119" title="MUST"> MUST insert: </em> have at least the insert: <code> AnnotationCollection insert: </code>
code> class (the name associated with OrderedCollection in the JSON-LD context) but insert: <em class="rfc2119" title="MAY"> MAY insert: </em> have other types as well, including the type of LDP Container used. It insert: <em class="rfc2119" title="SHOULD"> SHOULD insert: </em> have a human readable insert: <code> label insert: </code>
, and insert: <em class="rfc2119" title="MAY"> MAY insert: </em> have other properties such as insert: <code> creator insert: </code>
and insert: <code> created insert: </code>
. insert: </p>
If there are greater than zero Annotations in the Container, the representation delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST either include a link to the first page of Annotations as the value of the first
property, or include the representation of the first page embedded within the response. If there is more than one page of Annotations, then the representation delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD have a link to the last page using the last
property.
The representation of the Container delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD include the total
property with the total number of annotations in the Container. The Container insert: <em class="rfc2119" title="SHOULD"> SHOULD insert: </em> include the insert: <code> modified insert: </code>
property with the most recent timestamp of when any of the annotations in the Container. This timestamp allows clients to detect when to re-cache data, even if there are the same number of annotations as the same number may have been added and deleted.
The IRI of the Container provided in the response delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD differentiate between whether the pages contain just the IRIs, or the full descriptions of the Annotations. It is delete: <em title="RECOMMENDED" class="rfc2119"> insert: <em class="rfc2119" title="RECOMMENDED"> RECOMMENDED that this be done with a query parameter. The server delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY redirect the client to this IRI and deliver the response there, otherwise it delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST include a Content-Location
header with the IRI as its value.
There are three preferences for Container requests that will govern the representation of the server's responses:
Prefer
request header with the value return=representation;include="http://www.w3.org/ns/ldp#PreferMinimalContainer"
. Prefer
request header with the value return=representation;include="http://www.w3.org/ns/oa#PreferContainedIRIs"
. Prefer
request header with the value return=representation;include="http://www.w3.org/ns/oa#PreferContainedDescriptions"
. The client delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY send multiple preferences as the value of the include
parameter as defined by the Linked Data Platform [ delete: <a href="#bib-ldp" class="bibref"> insert: <a class="bibref" href="#bib-ldp"> ldp ]. However, the client delete: <em title="MUST NOT" class="rfc2119"> insert: <em class="rfc2119" title="MUST NOT"> MUST NOT include both the PreferContainedIRIs
and PreferContainedDescriptions
preferences on the same request, as the server cannot honor both at the same time. If the PreferMinimalContainer
preference is not given, then the server delete: <em title="MAY" class="rfc2119"> MAY delete: </em> respond with the first page of insert: <em class="rfc2119" title="SHOULD NOT"> SHOULD NOT insert: </em> embed the Annotations embedded within the Container response or it delete: <em title="MAY" class="rfc2119"> MAY delete: </em> provide links references to them, but insert: <em class="rfc2119" title="SHOULD"> SHOULD insert: </em> include a reference to the first and last pages. Annotation Pages. Whether the pages are of IRI references or complete descriptions is governed by the use of insert: <code> PreferContainedIRIs insert: </code>
and insert: <code> PreferContainedDescriptions insert: </code>
respectively. If no preference is given by the client, the server delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD default to the PreferContainedDescriptions
behavior. The server delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY ignore the client's preferences.
If the client requests the minimal representation of an Annotation Container, the response delete: <em title="MUST NOT" class="rfc2119"> insert: <em class="rfc2119" title="MUST NOT"> MUST NOT include either the ldp:contains
predicate nor embed the first page of Annotations within the response.
The linked pages delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD follow any PreferContainedDescriptions
or PreferContainedIRIs
preferences.
The server delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY return a representation without embedded Annotations, even if the PreferMinimalContainer
preference is not supplied.
GET /annotations/ HTTP/1.1 Host : example.org Accept : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Prefer : return=representation;include="http://www.w3.org/ns/ldp#PreferMinimalContainer http://www.w3.org/ns/oa#PreferContainedIRIs"
HTTP/1.1 200 OK Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" ETag : "_87e52ce123123" Link : <http://www.w3.org/ns/ldp#BasicContainer>; rel="type" Link : <http://www.w3.org/TR/annotation-protocol/>; rel="http://www.w3.org/ns/ldp#constrainedBy" Allow : POST,GET,OPTIONS,HEAD Vary : Accept Content-Length : 368 delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : [ "http://www.w3.org/ns/anno.jsonld" , "http://www.w3.org/ns/ldp.jsonld" ], delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/?iris=1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : [ "BasicContainer" , "AnnotationCollection" ], delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "total" : 42023 , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "modified" insert: </span> : insert: <span class="hljs-string"> "2016-07-20T12:00:00Z" insert: </span> , insert: <span class="hljs-attr"> "label" : "A Container for Web Annotations" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "first" : "http://example.org/annotations/?iris=1&page=0" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "last" : "http://example.org/annotations/?iris=1&page=42" }
If the Server supports Container preferences, it delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST respond to PreferContainedIRIs
with a response containing an AnnotationPage
as the value of first
with its items
containing only the IRIs of the contained Annotations.
The linked pages delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD follow the PreferContainedIRIs
preference.
The PreferContainedIRIs
and the PreferContainedDescriptions
preferences are mutually exclusive.
GET /annotations/ HTTP/1.1 Host : example.org Accept : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Prefer : return=representation;include="http://www.w3.org/ns/oa#PreferContainedIRIs"
HTTP/1.1 200 OK Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Content-Location : http://example.org/annotations/?iris=1 ETag : "_87e52ce123123" Link : <http://www.w3.org/ns/ldp#BasicContainer>; rel="type" Link : <http://www.w3.org/TR/annotation-protocol/>; rel="http://www.w3.org/ns/ldp#constrainedBy" Allow : POST,GET,OPTIONS,HEAD Vary : Accept, Prefer Content-Length : 397 delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : [ "http://www.w3.org/ns/anno.jsonld" , "http://www.w3.org/ns/ldp.jsonld" ], delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/?iris=1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : [ "BasicContainer" , "AnnotationCollection" ], delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "total" : 42023 , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "modified" insert: </span> : insert: <span class="hljs-string"> "2016-07-20T12:00:00Z" insert: </span> , insert: <span class="hljs-attr"> "label" : "A Container for Web Annotations" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "first" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/?iris=1&page=0" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "AnnotationPage" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "next" : "http://example.org/annotations/?iris=1&page=1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "items" : [ "http://example.org/annotations/anno1" , "http://example.org/annotations/anno2" , "http://example.org/annotations/anno3" , "http://example.org/annotations/anno4" , "http://example.org/annotations/anno5" , "http://example.org/annotations/anno6" , ... "http://example.org/annotations/anno999" , ] }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "last" : "http://example.org/annotations/?iris=1&page=42" }
If the Server supports Container preferences, it delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST respond to PreferContainedDescriptions
with a response containing an AnnotationPage
as the value of first
with its items
containing complete, inline Annotations.
The linked pages delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD follow the PreferContainedDescriptions
preference.
The PreferContainedIRIs
and the PreferContainedDescriptions
preferences are mutually exclusive.
GET /annotations/ HTTP/1.1 Host : example.org Accept : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Prefer : return=representation;include="http://www.w3.org/ns/oa#PreferContainedDescriptions"
HTTP/1.1 200 OK Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Allow : GET,OPTIONS,HEAD Vary : Accept, Prefer Content-Length : 924 delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : [ "http://www.w3.org/ns/anno.jsonld" , "http://www.w3.org/ns/ldp.jsonld" ], delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/?iris=0" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : [ "BasicContainer" , "AnnotationCollection" ], delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "total" : 42023 , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "modified" insert: </span> : insert: <span class="hljs-string"> "2016-07-20T12:00:00Z" insert: </span> , insert: <span class="hljs-attr"> "label" : "A Container for Web Annotations" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "first" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/?iris=0&page=0" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "AnnotationPage" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "next" : "http://example.org/annotations/?iris=0&page=1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "items" : [ { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : "http://example.net/body1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://example.com/page1" }, { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno2" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "TextualBody" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "value" : "I like this!" }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://example.com/book1" } // ... { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno50" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : "http://example.org/texts/description1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://example.com/images/image1" } ] }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "last" : "http://example.org/annotations/?iris=0&page=840" }
Individual pages are instances of delete: <code> CollectionPage delete: </code> . the Activity Streams insert: <code> OrderedCollectionPage insert: </code>
class, which is refered to as insert: <code> AnnotationPage insert: </code>
in the Web Annotation JSON-LD context. The page contains the Annotations, either via their IRIs or full descriptions, in the items
property.
The requirements for JSON-LD representation of Annotation Collections Pages are defined in the Web Annotation Data Model, and are summarized here. insert: </p>
insert: <p> The Annotation Page insert: <em class="rfc2119" title="MUST"> MUST insert: </em> have an IRI that identifies it, and insert: <em class="rfc2119" title="MUST"> MUST insert: </em> have at least the insert: <code> AnnotationPage insert: </code>
class but insert: <em class="rfc2119" title="MAY"> MAY insert: </em> have other types as well. If the Page is not the last Page in the Collection, then it insert: <em class="rfc2119" title="MUST"> MUST insert: </em> have a reference to the Page which follows it using the insert: <code> next insert: </code>
property. If the Page is not the first Page in the Collection, it insert: <em class="rfc2119" title="SHOULD"> SHOULD insert: </em> have a reference ot the previous Page using the insert: <code> prev insert: </code>
property. Pages insert: <em class="rfc2119" title="SHOULD"> SHOULD insert: </em> give the position of the first Annotation in the insert: <code> items insert: </code>
list relative to the order of the Collection using the zero-based insert: <code> startIndex insert: </code>
property. insert: </p>
Each page delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST have a link to the container Collection that it is part of, using the partOf
property. If it is not the first page, it delete: <em title="MUST" class="rfc2119"> MUST delete: </em> have a link to the previous page in the sequence, using the delete: <code> prev delete: </code> property. If it is not the last page, it delete: <em title="MUST" class="rfc2119"> MUST delete: </em> have a link to the next page in the sequence, using the delete: <code> next delete: </code> property. The description of the Collection insert: <em class="rfc2119" title="SHOULD"> SHOULD insert: </em> include both the insert: <code> total insert: </code>
and insert: <code> modified insert: </code>
properties. The response delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY include other properties of the Collection in the response, including the total number of items such as the insert: <code> label insert: </code>
or insert: <code> first insert: </code>
and insert: <code> last page insert: </code>
links.
The client delete: <em title="SHOULD NOT" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD NOT"> SHOULD NOT send the Prefer
header when requesting the page, Page, as it has already been taken into account when requesting the Container. Collection.
This specification does not require any particular functionality when a client makes requests other than GET, HEAD or OPTIONS to a page.
As the delete: <code> CollectionPage delete: </code> Page is not a an LDP Container, it does not have the requirement to include a Link
header with a type. That the URLs can could be constructed with query parameters added to the Container's IRI is an implementation convenience, and does not imply the type of the resource.
insert: <b> Embedded IRIs Interaction Example insert: </b> insert: </p>
GET /annotations/?iris=1&page=0 HTTP/1.1 Host : example.org Accept : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
HTTP/1.1 200 OK Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Allow : GET,OPTIONS,HEAD Vary : Accept, Prefer Accept Content-Length : 630 delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : "http://www.w3.org/ns/anno.jsonld" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/?iris=1&page=0" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "AnnotationPage" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "partOf" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/?iris=1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "total" : 42023 , insert: <span class="hljs-attr"> "modified" insert: </span> : insert: <span class="hljs-string"> "2016-07-20T12:00:00Z" insert: </span> , }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "startIndex" insert: </span> : insert: <span class="hljs-number"> 0 insert: </span> , insert: <span class="hljs-attr"> "next" : "http://example.org/annotations/?iris=1&page=1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "items" : [ "http://example.org/annotations/anno1" , "http://example.org/annotations/anno2" , "http://example.org/annotations/anno3" , "http://example.org/annotations/anno4" , "http://example.org/annotations/anno5" , "http://example.org/annotations/anno6" , ... "http://example.org/annotations/anno999" , ] }
insert: <b> Embedded Descriptions Interaction Example insert: </b> insert: </p>
insert: <div> GET /annotations/?iris=0&page=0 HTTP/1.1 Host : example.org Accept : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
HTTP/1.1 200 OK Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Allow : GET,OPTIONS,HEAD Vary : Accept, Prefer Content-Length : 924 delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : "http://www.w3.org/ns/anno.jsonld" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/?iris=0&page=0" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "AnnotationPage" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "partOf" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/?iris=0" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "total" : 42023 , insert: <span class="hljs-attr"> "modified" insert: </span> : insert: <span class="hljs-string"> "2016-07-20T12:00:00Z" insert: </span> , }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "startIndex" insert: </span> : insert: <span class="hljs-number"> 0 insert: </span> , insert: <span class="hljs-attr"> "next" : "http://example.org/annotations/?iris=0&page=1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "items" : [ { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : "http://example.net/body1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://example.com/page1" }, { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno2" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "TextualBody" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "value" : "I like this!" }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://example.com/book1" } // ... { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno50" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : "http://example.org/texts/description1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://example.com/images/image1" } ] }
As the IRI for Annotation Containers delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY be any IRI, and it is unlikely that every Web Server will support the functionality, it is important to be able to discover the availability of these services.
Any resource delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY link to an Annotation Container when Annotations on the resource delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD be created within the referenced Container. This link is carried in an HTTP Link
header and the value of the rel
parameter delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST be http://www.w3.org/ns/oa#annotationService
.
For HTML representations of resources, the equivalent link
tag in the header of the document delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY also be used.
For an example image resource, a GET request and response with a link to the above Annotation Container might look like:
Request: GET /images/logo.jpg HTTP/1.1 Host : example.com
HTTP/1.1 200 OK Content-Type : image/jpeg Link : <http://example.org/annotations/>; rel="http://www.w3.org/ns/oa#annotationService" Allow : GET Content-Length : 76983 delete: <span class="css"> delete: <span class="hljs-selector-attr"> insert: <span class="json"> [...] delete: </span>
New Annotations are created via a POST request to an Annotation Container. The Annotation, serialized as JSON-LD, is sent in the body of the request. All of the known information about the Annotation delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD be sent, and if there are already IRIs associated with the resources, they delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD be included. The serialization delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD use the Web Annotation JSON-LD profile, and servers delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY reject other contexts even if they would otherwise produce the same model. The server delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY reject content that is not considered an Annotation according to the Web Annotation specification [ delete: <a href="#bib-annotation-model" class="bibref"> insert: <a class="bibref" href="#bib-annotation-model"> annotation-model ].
Upon receipt of an Annotation, the server delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY assign IRIs to any resource or blank node in the Annotation, and delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST assign an IRI to the Annotation resource in the id
property, even if it already has one provided. The server delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD use HTTPS IRIs when those resources are able to be retrieved individually. The IRI for the Annotation delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST be the IRI of the Container with an additional component added to the end.
The server delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY add information to the Annotation. Possible additional information includes the agent that created it, the time of the Annotation's creation, or additional types and formats of the constituent resources.
If the Annotation contains a canonical
link, property, then it delete: <em title="MUST" class="rfc2119"> that reference insert: <em class="rfc2119" title="MUST"> MUST be maintained without change. If the Annotation has an IRI in the id
property, then it delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD be copied to the via
property, and the IRI assigned by the server, server at which the Annotation will be available, delete: <em title="MUST" class="rfc2119"> available insert: <em class="rfc2119" title="MUST"> MUST be put in the id
field to replace it.
The server delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST respond with a 201
Created response if the creation is successful, and an appropriate error code otherwise. The response delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST have a Location
header with the Annotation's new IRI.
POST /annotations/ HTTP/1.1 Host : example.org Accept : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Content-Length : 202 delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : "http://www.w3.org/ns/anno.jsonld" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "TextualBody" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "value" : "I like this page!" }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://www.example.com/index.html" }
HTTP/1.1 201 CREATED Allow : PUT,GET,OPTIONS,HEAD,DELETE,PATCH Location : http://example.org/annotations/anno1 Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Content-Length : 287 ETag : "_87e52ce126126" delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : "http://www.w3.org/ns/anno.jsonld" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "created" : "2015-01-31T12:03:45Z" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "TextualBody" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "value" : "I like this page!" }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://www.example.com/index.html" }
The IRI path segment that is appended to the Container IRI for a resource delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY be suggested by the Annotation Client by using the Slug
HTTP header on the request when the resource is created. The server delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD use this name, so long as it does not already identify an existing resource, but delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY ignore it and use an automatically assigned name.
POST /annotations/ HTTP/1.1 Host : example.org Accept : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Content-Length : 202 Slug : "my_first_annotation" delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : "http://www.w3.org/ns/anno.jsonld" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "TextualBody" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "value" : "I like this page!" }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://www.example.com/index.html" }
HTTP/1.1 201 CREATED Link : <http://www.w3.org/ns/ldp#BasicContainer>; rel="type" Allow : PUT,GET,OPTIONS,HEAD,DELETE,PATCH Location : http://example.org/annotations/my_first_annotation Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" ETag : "_87e52ce126126" Vary : Accept Content-Length : 301 delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : "http://www.w3.org/ns/anno.jsonld" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/my_first_annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "created" : "2015-01-31T12:03:45Z" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "TextualBody" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "value" : "I like this page!" }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://www.example.com/index.html" }
Annotations can be updated by using a PUT request to replace the entire state of the Annotation. Annotation Servers delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD support this method. Servers delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY also support using a PATCH request to update only the aspects of the Annotation that have changed, but that functionality is not specified in this document.
Replacing the Annotation with a new state delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST be done with the PUT method, where the body of the request is the intended new state of the Annotation. The client delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD use the If-Match
header with a value of the ETag it received from the server before the editing process began, to avoid collisions of multiple users modifying the same Annotation at the same time. This feature is not mandatory to support, as not every system will have multiple users with the potential to change a single Annotation, or use cases might dictate situatins in which overwriting is the desired behavior.
Servers delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD reject update requests that modify the values of the canonical
or via
properties, if they have been already set. set, unless business logic allows the request to be trusted as authoritatively correctly a previous error.
If successful, the server delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST return a 200 OK status with the Annotation as the body according to the content-type requested. As with creation, the server delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST return the new state of the Annotation in the response.
PUT /annotations/anno1 HTTP/1.1 Host : example.org Accept : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" Content-Length : 294 If-Match : "_87e52ce126126" delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : "http://www.w3.org/ns/anno.jsonld" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "created" : "2015-02-01T10:13:40Z" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "body" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "TextualBody" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "value" : "I REALLY like this page!" }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://www.example.com/index.html" }
HTTP/1.1 200 OK Content-Type : application/ld+json; profile="http://www.w3.org/ns/anno.jsonld" ETag : "_87e52ce234234" Link : <http://www.w3.org/ns/ldp#Resource>; rel="type" Allow : PUT,GET,OPTIONS,HEAD,DELETE,PATCH Vary : Accept Content-Length : 331 delete: <span class="xquery"> { delete: <span class="hljs-string"> insert: <span class="json"> { insert: <span class="hljs-attr"> "@context" : "http://www.w3.org/ns/anno.jsonld" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "id" : "http://example.org/annotations/anno1" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "Annotation" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "created" : "2015-02-01T10:13:40Z" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "modified" : "2015-02-02T20:43:19Z" "body" : { delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "type" : "TextualBody" , delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "value" : "I REALLY like this page!" }, delete: <span class="hljs-string"> insert: <span class="hljs-attr"> "target" : "http://www.example.com/index.html" }
Clients delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST use the DELETE HTTP method to request that an Annotation be deleted by the server. Annotation Servers delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD support this method. Clients delete: <em title="SHOULD" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD"> SHOULD send the ETag of the Annotation in the If-Match
header to ensure that it is operating against the most recent version of the Annotation.
If the DELETE request is successfully processed, then the server delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST return a 204 status response. The IRIs of deleted Annotations delete: <em title="SHOULD NOT" class="rfc2119"> insert: <em class="rfc2119" title="SHOULD NOT"> SHOULD NOT be re-used for subsequent Annotations. The IRI of the deleted Annotation delete: <em title="MUST" class="rfc2119"> insert: <em class="rfc2119" title="MUST"> MUST be removed from the Annotation Container it was created in. There are no requirements made on the body of the response, and it delete: <em title="MAY" class="rfc2119"> insert: <em class="rfc2119" title="MAY"> MAY be empty.
DELETE /annotations/anno1 HTTP/1.1 Host : example.org If-Match : "_87e52ce126126"
HTTP/1.1 204 NO CONTENT Content-Length : 0
This section is non-normative.
There are inevitably situations where errors occur when retrieving or managing Annotations. The use of the HTTP status codes below provides a method for clients to understand the reason why a request has failed. Some of the situations that might occur, and the preferred HTTP status code are given below. This list is intended to be informative and explanatory, rather than imposing additional requirements beyond those already established by HTTP.
Code | Example Situation |
---|---|
400 | The Annotation Client sent a request which the Annotation Server cannot process due to the request not following the appropriate specifications. |
401 | The Annotation Client is not authorized to perform the requested operation, such as creating or deleting an Annotation, as it did not supply authentication credentials. |
403 | The Annotation Client is not authorized to perform the requested operation, as the authentication credentials supplied did not meet the requirements of a particular access control policy for the Annotation or Annotation Container. |
404 | The Annotation or Annotation Container requested does not exist. |
405 | The requested HTTP method is not allowed for the resource, such as trying to POST to an Annotation Container page, or trying to PATCH an Annotation when that functionality is not supported. |
406 | The requested format for the Annotation or Annotation Container's representation is not available, for example if a client requested RDF/XML and the server does not support that (optional) transformation. |
409 | The Annotation Client tried to set or change a value that the server does not allow Clients to modify, such as the containment list of an Annotation Container or server set modification timestamps. |
410 | The Annotation is known to have existed in the past and was deleted. |
412 | The Annotation Client supplied an If-Match header that did not match the ETag of the Annotation being modified. |
415 | The Annotation Client sent an entity-body that is not able to be processed by the Server, such as non-Annotation or in a context that is unrecognized. |
This section is non-normative.
For this specification to be advanced to Proposed Recommendation, there must be at least two independent implementations of each feature described below. Each feature may be implemented by a different set of products, and there is no requirement that any single product implement every feature.
FeaturesFor the purposes of evaluating exit criteria, the following operations are considered as features:
Each feature must be implemented according to the requirements given in the specification, regarding the HTTP headers, status codes, and entity body. Software that does not alter its behavior in the presence or lack of a given feature is not deemed to implement that feature for the purposes of exiting the Candidate recommendation phase.
This section is non-normative.
delete: <section property="bibo:hasPart" resource="#changes-from-the-candidate-recommendation-of-2016-07-12" typeof="bibo:Chapter" id="changes-from-the-candidate-recommendation-of-2016-07-12"> delete: <h3 resource="#h-changes-from-the-candidate-recommendation-of-2016-07-12" id="h-changes-from-the-candidate-recommendation-of-2016-07-12"> insert: <section id="changes-from-the-candidate-recommendation-of-2016-09-06" typeof="bibo:Chapter" resource="#changes-from-the-candidate-recommendation-of-2016-09-06" property="bibo:hasPart">Editorial changes in this specification from the insert: <a href="http://www.w3.org/TR/2016/CR-annotation-protocol-20160906/"> Candidate Recommendation of 2016-09-06 insert: </a> are: insert: </p>
insert: <ul>Editorial changes in this specification from the Candidate Recommendation of 2016-07-12 are:
Prefer
header when the client has multiple preferences. Significant technical changes in this specification from the Working Draft Published of 2016-03-31 are:
The Web Annotation Working Group gratefully acknowledges the contributions of the Open Annotation Community Group . The output of the Community Group was fundamental to the current data model and protocol.
The following people have been instrumental in providing thoughts, feedback, reviews, content, criticism and input in the creation of this specification: