On this page

AnnotationAPI

Cross Reference Annotations

This section describes how cross-referencing (i.e. a reference from one annotation or text to another annotation or text) is implemented. All annotations conform to the W3C Web Annotation Data Model. To simplify processing in TIDO, some keys have been added.

A cross-reference requires three components:

1. An origin — an HTML element that is either located in an HTML serialisation of an item or in the body of another annotation.
2. The cross-reference annotation — a specific form of annotation.
3. A destination of the cross-reference — a piece of text in an annotation or HTML serialisation that is the endpoint of the cross-reference.

All components (if the source is an annotation) share the same top-level structure but differ in the structure of their body.

---

Common Top-Level Structure

All annotation objects share the following top-level fields:

Top-Level Structure

Field	Type	Description
type	string	Always "Annotation".
id	URI	A unique IRI identifying this annotation.
body	object	Describes the content or destination of the annotation. Structure varies by annotation type.
target	array	Describes the source passage(s) or element(s) that trigger this annotation.

---

Target Structure

The target array is shared across all components and always has the same structure:

Example

Code
"target": [
  {
    "selector": {
      "type": "CssSelector",
      "value": "#some-element-id"
    },
    "format": "text/html",
    "language": "en",
    "source": "https://example.com/html/some-file.html"
  }
]

Target

Field	Type	Required	Description
selector.type	string	yes	Always "CssSelector".
selector.value	string	yes	A CSS ID selector identifying the HTML element that is the origin of the cross-reference.
format	string	yes	The MIME type of the source. Either "text/html"/"application/xhtml+xml" for HTML files or "application/json" for an annotation.
language	string	no	The language of the source document as an ISO 639-3 code.
source	URI	yes	The URL of the HTML file or annotation page in which the HTML element referenced by selector.value occurs.

---

Component 1: The Origin Element

The origin element can either be a passage in an HTML serialisation of an item or an HTML element in the body of an annotation.

For documentation of referencing a piece of text in an HTML serialisation, see General Annotations. The following example describes annotations as origin elements.

Example

Code
{
  "type": "Annotation",
  "id": "https://example.com/annotations/annotationPage/1/ftn1",
  "body": {
    "type": "TextualBody",
    "value": "Some text <span id='id1' class='crossref'>that has a passage referencing to another text</span>.",
    "format": "text/html",
    "annotationType": "EditorialNote"
  },
  "target": [
    {
      "selector": {
        "type": "CssSelector",
        "value": "#ref-ftn1"
      },
      "format": "text/html",
      "language": "en",
      "source": "https://example.com/api/html/item-1.html"
    }
  ]
}

Body Structure

Body

Field	Type	Description
type	string	Always "TextualBody".
value	string	The content of the annotation. May contain inline HTML including <span> elements with cross-reference markup.
format	string	The MIME type of value (e.g. "application/xhtml+xml" or "text/html").
annotationType	string	An arbitrary value (e.g. "EditorialNote").

Cross-Reference Markup in value

The value field may contain <span> elements that mark cross-references within the annotation text:

Example

Code
<span id='id1' class='crossref'>
  that has a passage referencing to another text
</span>

Cross-Reference Markup

Attribute	Description
id	A unique ID for this cross-reference, used as the selector target in a corresponding cross-reference annotation.
class	Always "crossref" — used by the client to identify cross-reference elements.

---

Component 2: The Cross-Reference Annotation

A cross-reference annotation links an origin element (in a text or another annotation) to a target passage (in a text or another annotation).

Example 1: Referencing an Annotation

Code
{
  "type": "Annotation",
  "id": "https://example.com/annotations/annotationPage/1/id1",
  "body": {
    "type": "SpecificResource",
    "annotationType": "CrossRef",
    "format": "application/json",
    "source": {
      "id": "https://example.com/api/annotations/annotationPage/1/intro-ftn2",
      "collection": "https://example.com/api/collections/Shakespeares_works",
      "manifest": "https://example.com/api/manifests/Othello",
      "item": "https://example.com/api/items/act_1",
    }
  },
  "target": [
    {
      "selector": {
        "type": "CssSelector",
        "value": "#id1"
      },
      "format": "application/json",
      "source": "https://example.com/annotations/annotationPage/1/ftn1"
    }
  ]
}

Example 2: Referencing an Element in an HTML File

Code
{
  "type": "Annotation",
  "id": "https://example.com/api/annotations/annotationPage/1/id1",
  "body": {
    "type": "SpecificResource",
    "annotationType": "CrossRef",
    "format": "text/html",
    "selector": {
      "type": "CssSelector",
      "conformsTo": "http://tools.ietf.org/rfc/rfc3236",
      "value": "#line_20"
    },
    "source": {
      "id": "https://example.com/api/html/item-2.html",
      "collection": "https://example.com/api/collections/Shakespeares_works",
      "manifest": "https://example.com/api/manifests/Othello",
      "item": "https://example.com/api/items/act_2"
    }
  },
  "target": [
    {
      "selector": {
        "type": "CssSelector",
        "value": "#id1"
      },
      "format": "text/html",
      "source": "https://example.com/annotations/annotationPage/1/ftn1"
    }
  ]
}

Body Structure

Body

Field	Type	Description
type	string	Always "SpecificResource" — identifies this as a pointer to a specific element within a resource.
annotationType	string	Always "CrossRef" — identifies this as a cross-reference annotation.
format	string	The MIME type of the destinated resource.
selector.type	string	Always "CssSelector".
selector.conformsTo	URI	Indicates that the selector conforms to the RFC 3236 fragment identifier specification.
selector.value	string	A CSS ID selector identifying the target element within the HTML document.
source	object	Describes the destination to which the client should navigate when this cross-reference is activated.
source.id	URI	The IRI of the target annotation or HTML file.
source.collection	URI	The IRI of the TextAPI collection containing the target.
source.manifest	URI	The IRI of the TextAPI manifest containing the target.
source.item	URI	The IRI of the TextAPI item containing the target.

---

Comparison of Body Structures

Comparison of Body Structures

Feature	Origin Element	CrossRef → Annotation	CrossRef → Text Passage
body.type	"TextualBody" or not applicable	"SpecificResource"	"SpecificResource"
body.annotationType	arbitrary (see General Annotations) or not applicable	"CrossRef"	"CrossRef"
body.value	HTML string or not applicable	—	—
body.selector	—	—	CSS selector of destination element
body.source	—	TextAPI location object with fromat: "application/json"	TextAPI location object with format: "text/html"
Navigation target	—	Another annotation	A specific element in an HTML document

---

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.annotationType
• body.source.collection
• body.source.manifest
• body.source.item