Annotation format

The best way to think of an annotation is in its json serialization. In that form a standard annotation looks like:

    {
      "account_id": null, 
      "created": "2011-05-24T18:52:08.036814", 
      "text": "A note I wrote", 
      "tags": [
        "a-tag"
      ], 
      "uri": null, 
      "ranges": [
        {
          "start": "/p[69]/font/font", 
          "end": "/p[70]/font/font", 
          "startOffset": 0, 
          "endOffset": 120
        }
      ], 
      "annotator_schema_version": "v1.0", 
      "user": {
        "id": "the-user-id"
      }, 
      "quote": null, 
      "id": "39fc339cf058bd22176771b3e3187329", 
      "permissions": {
        "read": [], 
        "admin": [], 
        "update": [], 
        "delete": []
      }

Note that this annotation includes some info stored by plugins (notably the Permissions Plugin and Tags Plugin). In its absolute simplest form the annotation would be (comments start with a hash ...):

    {
      "id": "39fc339cf058bd22176771b3e3187329",
      # This field is automatically created by backend on save
      "created": "2011-05-24T18:52:08.036814",
      # A uri identifying the document being annotated
      # This field is not automatically created but must be specified when setting up Store Plugin
      "uri": "http://some.uri",
      # Text of annotation
      "text": "A note I wrote",
      # The text being annotated (stripped of formatting)
      "quote": "The lady said this.",
      # The text ranges in the source document to which the annotation is attached
      # Uses xpath plus character offset
      "ranges": [
        {
          "start": "/p[69]/font/font", 
          "end": "/p[70]/font/font", 
          "startOffset": 0, 
          "endOffset": 120
        }
      ], 
      "annotator_schema_version": "v1.0"
}

This basic schema can be added to by plugins -- any fields added by frontend should be preserved by backend implementations. For example, the Store Plugin (which adds persistence of annotations) allow you to specify arbitrary additional fields using the annotationData attribute.

Other Formats

• http://www.openannotation.org/