[annotator-dev] Annotator / Open Annotation mapping

Robert Sanderson azaroth42 at gmail.com
Wed Jun 18 21:40:35 UTC 2014

Dear all,

Below is the result of a discussion between Randall and I regarding my Open
Annotation tickets.

Simple translations:

* "@context" and "@type" are added.
* "id" becomes "@id", with a value of the base URL of the API (passed to
the function) plus /annotations/ plus the current id value.
* "annotator_schema_version" goes away.
* if "updated" is present, it becomes "annotatedAt". If not, then "created"
becomes "annotatedAt".
* "text" becomes the construction:
    "hasBody" : {"@type" : "cnt:ContentAsText", "chars" : "content-here"}
* "user" becomes "annotatedBy" : {"foaf:nick" : "userid-here"}

Tag logic:

The current annotator documentation doesn't say whether the tag is about
the comment/body/text, the annotation resource, or the

Making a stand that they're actually about the target (despite the "review"
example), then they become additional bodies:

"hasBody" : [ {...as above ...}, {"@type" : ["cnt:ContentAsText",
"oa:Tag"], "chars" : "tag-here"}]

And if they're not about the target, then they get dropped.

Target logic:

If there are no ranges or quote, then "uri" becomes "hasTarget".
If there is quote, but no ranges:

"hasTarget" : {
  "@type" : "oa:SpecificResource",
  "hasSource" : "uri-here",
  "hasSelector" : {
    "@type" : "oa:TextQuoteSelector",
    "exact" : "quote-here"

If there is quote and ranges, it becomes longer and uses a custom selector
(until we can standardize it in the W3C WG)

"hasTarget" : {
  "@type": "oa:SpecificResource",
  "hasSource" : "uri-here",
  "hasSelector" : {
     "@type" : "oa:Choice",
     "default" : {
        "@context" : "http://annotatorjs.org/ns/oa-context.json",
        "@type" : "anno:Range",
        "start": "/p[69]/span/span",
        "end": "/p[70]/span/span",
        "startOffset": 0,
        "endOffset": 120
     "item" : {
       "@type" : "oa:TextQuoteSelector",
        "exact" : "quote-here"

* Consumer and Permissions are dropped, as authorization isn't part of the
OA model.

Any comments before coding commences would be appreciated :)


Rob Sanderson
Technology Collaboration Facilitator
Digital Library Systems and Services
Stanford, CA 94305
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/annotator-dev/attachments/20140618/291fef50/attachment-0003.html>

More information about the annotator-dev mailing list