Re: Essence of the annotation protocol

Hi Ray,

Comments inline...

On Tue, Mar 31, 2015 at 10:24 PM, Denenberg, Ray <rden@loc.gov> wrote:

>  I have written the following scenario which I think represents that
> essence of the protocol insofar as my needs are concerned.  Could one (or
> more) of you (e.g. Rob)  look at this and see if it looks right.  And if it
> does, would it be useful to add something like this to the document.
>
I think a walkthrough would be a good non-normative section, or perhaps
second document.


> Step 1. Making a resource “Annotation-Friendly”
> Sue creates a resource http://example.com /sues-resources/resource1 .
She want it to be “annotation-friendly”;  that is, she want  to enable
annotations on that resource.
> She creates an annotation container for the resource:
> http://example.com /sues-resources/resource1/annotations/
> It advertises itself, as described in 3.1.1.

The annotations container could be at that URI, or it could be somewhere
else.  The important thing is that the service's URI is advertised so that
clients can know where to send the annotations.


>  > Step 2. Creating an Annotation Resource
> > Fred has created and wants to submit an annotation for
> http://example.com/ sues-resources/resource1.    He needs to post that
> annotation to the container,
> http://example.com/sues-resources/resource1/annotations/  .  But first he
> needs to discover that URI.   He can do that via a GET or HEAD on the
> resource, http://example.com/sues-resources/resource1  as described in
> examples 3 and 4.
> > Having discovered the container URI , Fred posts the annotation to it
> (see example 10).   As a result the server:
> >
> > Creates an annotation resource.
> > Lists the URI of the created annotation resource in the container.
> > Returns a  response which includes:
> >
> > The annotation as submitted.
> > Additional information, for example “annotatedAt”.
> > The URI of the created annotation.
> > See example 10.
>

Yes. The server will return the annotation as it has modified it to
potentially add in the URI it created, add annotatedAt and potentially
other provenance, and maybe some restructuring, for example to turn a
literal body into a resource.


> Step 3. Discovering the Annotations
>
> Finally, Lydia, a researcher, discovers resource http://example.com
/sues-resources/resource1 and wants to find its annotations.   She first
needs to find the URI of its annotation container. She does so in the same
manner that Fred did in step 2.  She then does a GET on that URI, and, as
seen in example 2, the list of annotation URIs are provided.

That's also correct.

  Now I realize there is much more complexity to the protocol and this is
> an oversimplification, but I reiterate, this (if I got it right) captures
> the essence, for my purposes.
>
Not much more complexity :) I think you've captured the important bits well.



> Question:  The protocol also calls for creation of Body and Other
> containers.  Is it really necessary to expose this in the protocol?
>
No, in my next draft (hopefully for next week) I'll remove these.  The
annotation can be created by POSTing the entire set of triples to the
/annotations/ endpoint, and the decision was that creating non-RDF
resources is out of scope for the protocol to specify.  We can just
reference LDP for how these should be handled in general.

Rob

-- 
Rob Sanderson
Information Standards Advocate
Digital Library Systems and Services
Stanford, CA 94305