On this page

AnnotationAPI

Synoptic Annotations

This section describes the structure of synoptic annotations, which link one or more pieces of text across different serialisations of an item or even across items. These pieces are considered parallel or related, for example, when the same passage appears in two different texts or to link the original text with a translation.

TIDO uses synoptic annotations to synchronise scrolling in panes and/or panels and to highlight connected text passages.

Synoptic annotations are based on the W3C Web Annotation Data Model and express multidirectional connections between text passages across one or more items of a TextAPI collection. All passages are considered equal partners in the relationship. For this reason, all passages are encoded as targets rather than placing one in the body and the rest in the target of an annotation. A body is intentionally omitted.

Synoptic connections within a single item (e.g. between a text and its translation) and synoptic connections between different items (e.g. between two different texts) are encoded using the same structure. This simplifies the creation and processing of annotations, as no distinction needs to be made between the two cases at annotation creation time.

---

Top-Level Structure

The response is a single AnnotationPage object:

Example:

Code
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "https://example.com/api/annotationPage",
  "type": "AnnotationPage",
  "partOf": {
    "id": "https://example.com/api/annotationCollection",
    "label": "Synopsis connections"
  },
  "next": null,
  "prev": null,
  "items": […]
}

AnnotationPage

Field	Type	Description
@context	URI	The TextAPI context.
id	URI	The IRI of this AnnotationPage.
type	string	Always AnnotationPage.
partOf.id	URI	The IRI of the parent AnnotationCollection.
partOf.label	string	A human-readable label for the parent collection.
next	URI | null	IRI of the next page in the collection, or null if this is the last page.
prev	URI | null	IRI of the previous page in the collection, or null if this is the first page.
items	array	The list of Annotation objects on this page.

---

Annotation Structure

Each item in items is an Annotation object with the following structure:

Example:

Code
{
  "type": "Annotation",
  "id": "https://example.com/api/annotationPage/synopsis-1",
  "target": […]
}

Annotation

Field	Type	Description
type	string	Always Annotation.
id	URI	A unique IRI identifying this annotation.
target	array	An array of target objects representing the passages connected by this synopsis.

Note that there is no body in a synoptic annotation. The relationship is expressed entirely through the targets.

---

Target Structure

Each entry in the target array identifies a specific passage within a specific HTML rendering of a TextAPI item:

Example:

Code
{
  "selector": {
    "type": "CssSelector",
    "value": "#s4j_fpw_nyb"
  },
  "source": {
    "id": "https://example.com/api/html/text_1.html",
    "collection": "https://example.com/api/collections/coll1",
    "manifest": "https://example.com/api/manifests/manifest1",
    "item": "https://example.com/api/items/item1"
  },
  "format": "text/html"
}

Target

Field	Type	Description
selector.type	string	Always CssSelector.
selector.value	string	A CSS ID selector identifying the target element within the HTML document.
source.id	URI	The IRI of the HTML document in which the target element can be found.
source.collection	URI	The IRI of the TextAPI collection this passage belongs to.
source.manifest	URI	The IRI of the TextAPI manifest this passage belongs to.
source.item	URI	The IRI of the TextAPI item this passage belongs to.
format	string	The media type of the source document.

The source object extends the standard W3C Web Annotation source field with additional TextAPI-specific properties (collection, manifest, item) to allow consumers to resolve the passage within the TextAPI hierarchy without having to dereference the HTML document itself.

---

Example 1: Synopsis within a Single Item

This example connects two different views (text and translation) of the same passage within the same TextAPI item:

Example:

Code
{
  "type": "Annotation",
  "id": "https://example.com/api/annotationPage/synopsis-1",
  "target": [
    {
      "selector": {
        "type": "CssSelector",
        "value": "#s4j_fpw_nyb"
      },
      "source": {
        "id": "https://example.com/api/html/text_1.html",
        "collection": "https://example.com/api/collections/coll1",
        "manifest": "https://example.com/api/manifests/manifest1",
        "item": "https://example.com/api/items/item1"
      },
      "format": "text/html"
    },
    {
      "selector": {
        "type": "CssSelector",
        "value": "#vxp_bdh_qbc"
      },
      "source": {
        "id": "https://example.com/api/html/text_1_translation.html",
        "collection": "https://example.com/api/collections/coll1",
        "manifest": "https://example.com/api/manifests/manifest1",
        "item": "https://example.com/api/items/item1"
      },
      "format": "text/html"
    }
  ]
}

Both targets reference the same manifest and same item, but different HTML documents (text_1.html vs. text_1_translation.html) and different CSS selectors.

---

Example 2: Synopsis between Different Items

This example connects a passage in "Text 1" with a parallel passage in "Text 2":

Example:

Code
{
  "type": "Annotation",
  "id": "https://example.com/api/annotationPage/synopsis-2",
  "target": [
    {
      "selector": {
        "type": "CssSelector",
        "value": "#s4j_fpw_nyb"
      },
      "source": {
        "id": "https://example.com/api/html/text_1.html",
        "collection": "https://example.com/api/collections/coll1",
        "manifest": "https://example.com/api/manifests/manifest1",
        "item": "https://example.com/api/items/item1"
      },
      "format": "text/html"
    },
    {
      "selector": {
        "type": "CssSelector",
        "value": "#rlh_tfd_m2c"
      },
      "source": {
        "id": "https://example.com/api/html/text_2.html",
        "collection": "https://example.com/api/collections/coll1",
        "manifest": "https://example.com/api/manifests/manifest2",
        "item": "https://example.com/api/items/item2"
      },
      "format": "text/html"
    }
  ]
}

The two targets reference different manifests (manifest1 vs. manifest2) and different items, while both belong to the same collection.

Added Properties

The following terms have been added in comparison to the W3C Web Annotation Data Model to simplify navigation to the target for TIDO:

• body.source.collection
• body.source.manifest
• body.source.item