JSON annotation format

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