JSON annotation format

The ​JSON format for annotations is based on the ​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 (​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 ​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
  }
}]