IIIF &
Web Annotation
3D TSG Meeting
May 17, 2023
IIIF Presentation API 3 Review
A Canvas may have:
With this much of the data model, we can present an object with a series of empty “views”. To add content to the empty Canvases, we use annotations.
Web Annotation Data Model
An annotation is considered to be a set of connected resources, typically including a body and target, and conveys that the body is related to the target. The exact nature of this relationship changes according to the intention of the annotation, but the body is most frequently somehow "about" the target.
https://www.w3.org/TR/annotation-model/
Adding Content to IIIF Canvas via Annotations
The annotation is made up of two parts. The body which is the resource you want to annotate on to something and the target which is the thing you are annotating. Examples of bodies might be:
A target might be:
Minimal Annotation to “Paint” a IIIF Canvas
{
"id": "https://example.org/anno/123",
"type": "Annotation",
"motivation": "painting",
"body": {
"id": "http://example.org/image/image-1.png",
"type": "Image",
"format": "image/png",
},
"target": "https://example.org/object/1/canvas/1"
}
Web Resources as Body/Target
Annotations most often reference external web resources as their Body and/or Target.
Embedded Textual Body
When the annotation body content is text, there is the option to include it directly in the JSON. using the TextualBody type:
{
"id": "http://example.org/anno5",
"type": "Annotation",
"body": {
"type" : "TextualBody",
"value" : "<p>j'adore !</p>",
"format" : "text/html",
"language" : "fr"
},
"target": "http://example.org/canvas/1"
}
An even more compact method is to use the stringBody property instead of body ( https://www.w3.org/TR/annotation-model/#string-body )
Motivation
The motivation property indicates the reason why the annotation was created.
The Web Annotation specification defines a number of motivation values, including commenting, describing, highlighting, linking, and tagging.
The IIIF Presentation API defines two motivations:
IIIF maintains a registry of motivations at https://iiif.io/api/registry/motivations/
Review: Painting an Entire Canvas with an Image
{
"id": "https://example.org/anno/123",
"type": "Annotation",
"motivation": "painting",
"body": {
"id": "http://example.org/image/image-1.png",
"type": "Image",
"format": "image/png",
},
"target": "https://example.org/object/1/canvas/1"
}
Annotating Part of the Canvas
We often wish to reference only part of the target (or body) resource. For example, we may have transcription or OCR of a line of text within the page. The annotation should target the region of the IIIF Canvas that contains the line, not the entire page.
There are two mechanisms for accomplishing this:
Example: URI with fragment
{
"id": "https://example.org/anno/123",
"type": "Annotation",
"motivation": "commenting",
"body": {
"id": "http://example.org/comment/1",
"type": "TextualBody",
"value": "this line is indecipherable”,
"format": "text/plain",
},
"target": "https://example.org/object/1/canvas/1#xywh=200,600,800,30"
}
Example: with FragmentSelector
{
"id": "https://example.org/anno/123",
"type": "Annotation",
…
"target": {
…
"source": "https://example.org/object/1/canvas/1",
"selector": {
"type": "FragmentSelector",
"conformsTo": "http://www.w3.org/TR/media-frags/",
"value": "xywh=200,600,800,30"
}
}
}
Example: XPathSelector
{
"id": "http://example.org/anno22",
"type": "Annotation",
"motivation": "commenting",
"target": "https://example.org/object/1/canvas/1",
"body": {
"source": "http://example.org/page1.html",
"selector": {
"type": "XPathSelector",
"value": "/html/body/p[2]/table/tr[2]/td[3]/span"
}
}
}
Additional SpecificResource Properties
SpecificResources may have additional properties, including:
Advanced Annotations: Choice
An annotation body may have the type Choice, which provides a list of alternative resources. The client may select a resource from the list to display or provide an interface to allow selection by the user.
Although rarely used, there are some not uncommon use cases for this in IIIF:
{
"@context": "http://www.w3.org/ns/anno.jsonld",
"id": "http://example.org/anno10",
"type": "Annotation",
"body": {
"type": "Choice",
"items": [
{
"id": "http://example.org/note1",
"language": "en"
},
{
"id": "http://example.org/note2",
"language": "fr"
}
]
},
"target": "http://example.org/website1"
}
Advanced Annotations:
Cardinality of Bodies and Targets
An annotation may have no Body (e.g., highlighting)
Annotations may have multiple Bodies and Targets. “In this case, each Body is considered to be equally related to each Target individually, rather than to the set of all of the Targets.”
Appendix D (non-normative) defines additional patterns that could be used to assert different semantics:
{
"id": "https://example.org/1",
"type": "Annotation",
…
"target": [
"http://example.org/image1",
]
}
Additional Annotation Properties
The Web Annotation Data model defines additional properties to meet these use cases:
IIIF Cookbook
The IIIF Cookbook assembles “recipes” for IIIF resources, including annotations.
URL: https://iiif.io/api/cookbook/
For example, “Simplest Annotation” https://iiif.io/api/cookbook/recipe/0266-full-canvas-annotation/
Recipes are useful for content publishers and developers of IIIF viewers. The cookbook has an associated matrix of viewer support for the various recipes: https://iiif.io/api/cookbook/recipe/matrix/
If we are implementing analogous functionality we should follow existing patterns to the extent possible.