On this page

AnnotationAPI

Introduction

The AnnotationAPI augments content provided via the TextAPI with additional information. This API primarily implements a subset of the W3C Web Annotation specifications, focusing on textual and related material such as audio snippets or image fragments that correspond to specific text sections.

This specification is constrained by the capabilities of the main client application, TIDO Viewer. For instance the target selectors have been restricted to a set the application has implemented focusing on a HTML serlialization. For the complete specification, refer to the Pydantic Models documentation.

---

General Annotations

This section describes a specialised subset of the W3C Web Annotation Data Model, tailored for the Editions ecosystem. It assumes a basic understanding of the W3C Web Annotation Data Model.

This subset is used to represent annotations on digital resources, such as linguistic annotations on HTML documents or editorial commentaries. Some properties have been added specifically for the TIDO client.

---

JSON Structure Breakdown

Root Object: AnnotationPage

Example

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

AnnotationPage

Property	Type	Description
@context	string	JSON-LD context, defining the vocabulary used (W3C Web Annotation).
id	string (URI)	Unique identifier for this AnnotationPage.
type	string	Must be "AnnotationPage".
partOf	object	Reference to the parent AnnotationCollection.
partOf.id	string (URI)	URI of the parent Annotation Collection.
partOf.label	string	A human-readable title for the parent Annotation Collection.
next	string/null	URI of the next AnnotationPage (for pagination), or null if none.
prev	string/null	URI of the previous AnnotationPage (for pagination), or null if none.
startIndex	integer	Zero-based index of the first annotation in this page.
items	array	List of Annotation objects.

---

Annotation Object

Example

Code
{
  "body": {…},
  "target": […],
  "type": "Annotation",
  "id": "https://example.com/api/manifest1/annotationPage/iff_5vk_b1c"
}

Annotation

Property	Type	Description
id	string (URI)	Unique identifier for this annotation.
type	string	Must be "Annotation".
body	object	The content of the annotation (e.g. text, comment, tag).
target	array	One or more targets (resources or parts thereof) being annotated.

---

Body Object

Example

Code
{
  "type": "TextualBody",
  "value": "<span class='ana'>*-Inf. *.Sg.</span>",
  "format": "text/html",
  "annotationType": "Linguistic"
}

Body

Property	Type	Description
type	string	Type of the body (e.g. "TextualBody") according to the W3C Web Annotation Data Model.
value	string	The actual content of the annotation (e.g. HTML, plain text).
format	string	MIME type of the value (e.g. "text/html").
annotationType	string	Application-specific type (e.g. "Linguistic"). This value is arbitrary and can be customised by the user.

---

Target Object

Example

Code
{
  "selector": {
    "type": "CssSelector",
    "value": "#iff_5vk_b1c"
  },
  "format": "application/xhtml+xml",
  "language": "de",
  "source": "https://example.com/api/html/serialization_1.html"
}

Target

Property	Type	Description
selector	object	Describes how to locate the target within the resource. MUST be CssSelector.
format	string	MIME type of the target resource (e.g. "application/xhtml+xml").
language	string	Language of the target resource (e.g. "de" for German).
source	string	URI of the target resource.

---

Selector Object

Example

Code
{
  "type": "CssSelector",
  "value": "#iff_5vk_b1c"
}

Selector

Property	Type	Description
type	string	Type of selector. MUST be "CssSelector".
value	string	The selector value (e.g. "#iff_5vk_b1c").

---

Example Use Case

The provided example shows a linguistic annotation on a German HTML document. The annotation:

• Has a unique ID: https://example.com/api/manifest1/annotationPage/iff_5vk_b1c
• Annotates the element with CSS selector #iff_5vk_b1c
• Provides a linguistic tag: <span class='ana'>*-Inf. *.Sg.</span>
• Is part of a larger collection: Annotations for manifest1

---

Usage Notes

• Pagination: Use next and prev for navigating between pages of annotations.
• Extensibility: Additional properties can be added as needed, following the W3C model. Ensure the JSON-LD context is adjusted to maintain interoperability.
• Validation: Ensure all URIs are resolvable and all required fields are present. For general validation, use WAPCAS.

---

Added Properties

• body.annotationType

---

Conformance

This annotation format conforms to the following specifications:

• W3C Web Annotation Data Model
• W3C Web Annotation Vocabulary
• W3C Selectors and States (for CssSelector)