W3C Team

Storing Annotations

Status: [2001-09-19] this document is obsolete. The Annotea Protocols document supercedes this one.

See also: requirements for storing annotations.

@@ how much of the XLink 'external linkbase' "protocol" can be reused for this purpose. Ans: not much, apparently. There doesn't seem to be a real "protocol" yet. We can transform the properties we have into full XLink properties but the result is larger due to everything being an XLink external locator.

@@ how much can we/do we care to leverage WEBDav for storing/ retrieving annotations.

Request

To create a new annotation, the client posts a chunk of RDF to a selected annotation service:

POST /Annotation HTTP/1.1
Content-Length:
Content-Type: application/rdf

<r:RDF xmlns:r="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:a="http://www.w3.org/1999/xx/annotation-ns#"
       xmlns:d="http://purl.org/dc/elements/1.0/">
 <r:Description>
  <r:type resource="http://www.w3.org/1999/xx/annotation-ns#Annotation"/>
  <r:type resource="http://www.w3.org/1999/xx/annotation-ns#Comment"/>
  <a:annotates r:resource="http://some.org/some/page.html"/>
  <a:context>#fragid</a:context>
  <d:creator>Ralph Swick</d:creator>
  <a:created>1999-10-14T12:10Z</a:created>
  <d:date>1999-10-14T12:10Z</d:date>
  <a:body>
   <r:Description/>
  </a:body>
 </r:Description>
</r:RDF>

Response

HTTP/1.1 201 Created
Location: http://www.w3.org/Annotation/3ACF6D754

<r:RDF xmlns:r="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:a="http://www.w3.org/1999/xx/annotation-ns#"
       xmlns:d="http://purl.org/dc/elements/1.0/">
 <r:Description about="http://www.w3.org/Annotation/3ACF6D754">
  <r:type resource="http://www.w3.org/1999/xx/annotation-ns#Annotation"/>
  <r:type resource="http://www.w3.org/1999/xx/annotation-ns#Comment"/>
  <a:annotates r:resource="http://some.org/some/page.html"/>
  <a:context>#fragid</a:context>
  <d:creator>Ralph Swick</d:creator>
  <a:created>1999-10-14T12:10Z</a:created>
  <d:date>1999-10-14T12:10Z</d:date>
  <a:body resource="http://www.w3.org/Annotation/3ACF6D754text"/>
 </r:Description> 
</r:RDF>

@@ Is it necessary to return all the properties? Since the client knows what it has sent, it could be sufficient to reply with:

HTTP/1.1 201 Created
Location: http://www.w3.org/Annotation/3ACF6D754

<r:RDF xmlns:r="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:a="http://www.w3.org/1999/xx/annotation-ns#"/>
 <r:Description about="http://www.w3.org/Annotation/3ACF6D754">
  <a:body resource="http://www.w3.org/Annotation/3ACF6D754text"/>
 </r:Description>
</r:RDF>

Notes

The value of the a:body property was posted as an anonymous resource. The annotation service generated a URI for this resource, so it is no longer anonymous. The URI is returned in the response so that the client can then PUT the annotation text:

PUT /Annotation/3ACF6D754text HTTP/1.1
Content-Length:
Content-Type: text/html

<html>
 <body>
  <p>This is an <em>important</em> concept.</p>
 </body>
</html>

Variants

If the client does not wish to have a separate resource for the (text) body it can be stored as a literal in the first request:

POST /Annotation HTTP/1.1
Content-Length:
Content-Type: application/rdf

<r:RDF xmlns:r="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:a="http://www.w3.org/1999/xx/annotation-ns#"
       xmlns:d="http://purl.org/dc/elements/1.0/">
 <r:Description>
  <r:type resource="http://www.w3.org/1999/xx/annotation-ns#Annotation"/>
  <r:type resource="http://www.w3.org/1999/xx/annotation-ns#Comment"/>
  <a:annotates r:resource="http://some.org/some/page.html"/>
  <a:context>#fragid</a:context>
  <d:creator>Ralph Swick</d:creator>
  <a:created>1999-10-14T12:10Z</a:created>
  <d:date>1999-10-14T12:10Z</d:date>
  <a:body>This is an important concept.</a:body>
 </r:Description> 
</r:RDF>

Note, however, that this method gives no way to attach a media type to the body of the annotation (Dan asserts that the media type of an RDF Literal is necessarily text/xml).

Request with separate body resource




Here is one way to express a POST that creates two resources.


POST /Annotation HTTP/1.1
Content-Length:
Content-Type: application/rdf

<r:RDF xmlns:r="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
       xmlns:a="http://www.w3.org/1999/xx/annotation-ns#"
       xmlns:d="http://purl.org/dc/elements/1.0/">
 <r:Description>
  <r:type resource="http://www.w3.org/1999/xx/annotation-ns#Annotation"/>
  <r:type resource="http://www.w3.org/1999/xx/annotation-ns#Comment"/>
  <a:annotates r:resource="http://some.org/some/page.html"/>
  <a:context>#fragid</a:context>
  <d:creator>Ralph Swick</d:creator>
  <a:created>1999-10-14T12:10Z</a:created>
  <d:date>1999-10-14T12:10Z</d:date>
  <a:body>
   <r:Description>
    <http:ContentType>text/html</http:ContentType>
    <http:ContentLength>2000</http:ContentLength>
    <http:Body r:parseType="Literal">
<html xmlns="http://www.w3.org/2000/xhtml">
 <head>
  <title>an annotation</title>
 </head>
 <body>
  this is my annotation
  <RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
  </RDF>
 </body>
</html>
    </http:Body>
   </r:Description/>
  </a:body>
 </r:Description> 
</r:RDF>






Results from Jose's Jan 2000 visit to be
integrated later done 2000-04-13 Rev 1.17









  Ralph, <swick@w3.org>

  $Date: 2001/09/19 19:10:59 $