= JSON annotation format =

The [[http://en.wikipedia.org/wiki/JSON|JSON]] format for annotations is based on the [[http://docs.annotatorjs.org/en/v1.2.x/annotation-format.html|Annotator.js annotation format]].

== Annotation ==

An annotation is an object that links a text (the annotation body) to a specific part (the selection) of a resource (the annotation target).

The JSON representation of an annotation has a few required elements while additional elements are added by optional plugins.

  id:: an identifier for the annotation, required for modifying and deleting annotations in the store.
  text:: the annotation body, required. ([[http://daringfireball.net/projects/markdown/syntax|Markdown syntax]] can be used with the Annotator Markdown plugin).
  uri:: identifies the annotation target, i.e. the annotated page, required for retrieving annotations from the store.
  ranges:: the selected text (see below) that was annotated, required for text.
  shapes:: the selected image region (see below) that was annotated, required for images.
  resource:: identifies the broader annotation target, e.g. the whole book if only one page was annotated as '''uri''', optional, provided by MPIWG viewer.
  user:: user that created the annotation, optional, provided by the Annotator Permissions plugin.
  permissions:: permissions for reading, updating, deleting and admin-ing the annotation, optional, provided by the Annotator Permissions plugin.

Example of an annotation:
{{{
{
  "id": "aHR0cDovL2VudGl0aWVMTM1MzQ5ODc1OTE5Nw",
  "text": "That would be [Charles Emmanuel](http://en.wikipedia.org/wiki/Charles_Emmanuel_I,_Duke_of_Savoy)",
  "uri": "http://echo.mpiwg-berlin.mpg.de/documents/experimental/digilib-test/benedetti-1585?pn=5",
  "ranges": [{
    "start":"/div[1]/div[2]/p[4]/span[1]",
    "startOffset":"16",
    "end":"/div[1]/div[2]/p[4]/span[1]",
    "endOffset":"33"}],
  "resource": "http://echo.mpiwg-berlin.mpg.de/documents/experimental/digilib-test/benedetti-1585",
  "user": {
    "id":"casties",
    "name":"Robert Casties",
    "uri":"http://entities.mpiwg-berlin.mpg.de/persons/casties"},
  "permissions": {
    "update":["casties"],
    "admin":["casties"],
    "delete":["casties"],
    "read":[]}
}
}}}


== Image selection ==

(State of 26.1.2015)

Annotations of images have a "shapes" member, specifying a list of regions on the image. The region definitions are based on the [[http://geojson.org/geojson-spec.html|GeoJSON format]] and the [[http://www.w3.org/TR/SVG/shapes.html|SVG shape definitions]]. 

The possible region forms are
  * point (x, y)
  * rectangle (x, y, width, height)
  * polygon (coordinates: [list of x,y])
  * linestring (coordinates: [list of x,y])

Coordinates and coordinate units are specified in a "geometry" member.

The coordinate unit "fraction" means that each coordinate is specified as a decimal fraction (float 0 <= x <= 1) of the image side length, e.g. x=0.03 means that x is at 3% of the total image width.

Example of an image area specification:
{{{
"shapes" : [{
  "type" : "rectangle",
  "geometry" : {
    "units" : "fraction",
    "x" : 0.0123, 
    "y" : 0.345,
    "width" : 0.5793,
    "height" : 0.734
  },
  {
  "type" : "polygon",
  "geometry" : {
    "units" : "fraction",
    "coordinates" : [[0.0123, 0.345], [0.5793, 0.734], [0.237, 0.554]]
  }
}]
}}}

== Text selection ==

Annotations of text have a "ranges" member, specifying a list of text ranges. 

The text range definitions use an XPath-like path to identify the '''start''' and '''end''' element and '''startOffset''' and '''endOffset''' character offsets inside the element.

The element paths use the web browser DOM and are rooted in the element that was specified when the Annotator Javascript was set up in the page.

Example of a text selection:
{{{
"ranges": [{
  "start" : "/div[1]/div[2]/p[4]/span[1]",
  "startOffset" : "16",
  "end" : "/div[1]/div[2]/p[4]/span[1]",
  "endOffset" : "33"
}]
}}}