Appearance
Annotate images with IIIF when you need to attach region-level scholarship (transcriptions, notes, links) that must stay portable across viewers and outlive any single tool. Skip it when whole-image captions or simple alt text would do, or when a spreadsheet of notes is genuinely enough. IIIF annotation is built on the W3C Web Annotation model, so its payoff is durability and reuse, not convenience for a one-off. This article is about the decision, not just the mechanics.
What exactly is a IIIF annotation?
A IIIF annotation is a W3C Web Annotation whose target points at a region of a canvas and whose body carries the content, a comment, a transcription, or a link. The motivation distinguishes purpose: painting annotations place the image itself on the canvas, while commenting, supplementing, or tagging annotations add scholarship on top. Structurally:
json
{
"type": "Annotation",
"motivation": "commenting",
"body": { "type": "TextualBody", "value": "Marginal gloss, 14th c. hand", "format": "text/plain" },
"target": "https://example.org/iiif/ms-12/canvas/3#xywh=1200,800,640,360"
}The #xywh= fragment pins the note to an exact rectangle.
When is IIIF annotation clearly worth it?
Reach for it when several of these are true: you are recording region-specific knowledge (which word is in which line, which figure is which saint); you want that knowledge usable in any compliant viewer, not locked in one platform; multiple people or institutions will contribute or consume it; and you expect the data to persist for years. Critical-edition transcription, art-historical iconography mapping, and crowdsourced line-by-line transcription all fit perfectly.
When should you not bother?
Be willing to say no. If your need is a single caption per image, IIIF annotation is heavy machinery for a screwdriver job, put it in the manifest metadata instead. If there is no genuine region-level scholarship, you are adding plumbing without payload. And if your team is two people who will read the notes in a spreadsheet, a spreadsheet wins. The honest test: would anyone outside your project ever consume these annotations? If not, the portability argument collapses.
Static manifest annotations or an annotation server?
This is the main architectural fork:
| Need | Approach | Storage |
|---|---|---|
| Fixed curatorial notes published with the object | Embed AnnotationPages in the manifest | The manifest file |
| User-created or evolving annotations | Run an annotation server | Separate, queryable store |
| Crowdsourced transcription at scale | Annotation server + Content Search | Database behind an API |
For evolving or user-generated content, run something like SimpleAnnotationServer or Annona so annotations are created, updated and served independently of the manifest.
How do you annotate irregular shapes?
Rectangles use the compact xywh media fragment. Anything else, an illuminated initial, a marginal sketch, a coastline on a map, needs an SVG selector so the region follows the actual shape:
json
"target": {
"source": "https://example.org/iiif/ms-12/canvas/3",
"selector": {
"type": "SvgSelector",
"value": "<svg><path d='M120,80 L300,90 L280,260 Z'/></svg>"
}
}This is the difference between "somewhere in that box" and "exactly this shape," which matters for iconographic precision.
What does annotation enable downstream?
Once annotation text is indexed and exposed through the IIIF Content Search API, viewers can search inside an object and jump to highlighted regions. For a transcribed register or codex, that turns a pile of images into a searchable text bound to its source pixels, the single most compelling reason institutions invest in IIIF annotation at all.
Key Takeaways
- IIIF annotations are W3C Web Annotations targeting canvas regions; the payoff is portability and longevity.
- Use them for region-level scholarship meant to be reused across viewers and time.
- Do not use them for whole-image captions or when a spreadsheet suffices.
- Embed fixed annotations in the manifest; run an annotation server for evolving or user-created ones.
- Use
xywhfor rectangles and SVG selectors for irregular shapes. - Indexed annotations plus the Content Search API make objects searchable.
Frequently Asked Questions
What standard underlies IIIF annotations?
The W3C Web Annotation Data Model. A IIIF annotation is a Web Annotation whose target is a region of a canvas, expressed with a media fragment selector or an SVG selector for non-rectangular shapes.
When is IIIF annotation the right choice?
When you need to attach scholarly notes, transcriptions or links to specific regions of an image, want them to be portable across viewers, and expect the annotations to outlive any single tool. That portability is the whole reason to choose IIIF over a bespoke tagging feature.
When should I NOT use IIIF annotation?
When you only need whole-image captions or simple alt text, when there is no region-level scholarship to record, or when a lightweight spreadsheet of notes would serve your team better at a fraction of the effort.
Do I need an annotation server?
For static, curatorial annotations you can embed them in the manifest. For user-created or evolving annotations you need a server such as SimpleAnnotationServer or Annona to store and serve AnnotationPages independently.
How are non-rectangular regions annotated?
With an SVG selector inside the annotation target. Rectangular regions can use the simpler xywh media fragment, but irregular shapes like an initial or a marginal drawing need SVG paths.
Can annotations be searched?
Yes. If you index annotation text and expose the IIIF Content Search API, viewers like Mirador can search within an object and highlight matching regions, which is powerful for transcribed manuscripts.