= JSON annotation format =

The [[http://en.wikipedia.org/wiki/JSON|JSON]] format for annotations is based on the [[https://github.com/okfn/annotator/wiki/Storage|Annotator Store API]].

== 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.

{{{
{
  "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 area ==

Annotations of image areas have a "shapes" member, specifying a list of shapes on the image. The shape definitions are based on the [[http://www.w3.org/TR/SVG/shapes.html|SVG shape definitions]]. 

The possible shape forms are
  * point
  * rectangle
  * polygon (not yet implemented)
  * circle (not yet implemented)

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.567,
    "height": 0.789
  }
}]
}}}