The IIIF Presentation API is the specification that describes the structure and meaning of a digitised object: which views (canvases) it contains, in what order, with what metadata, rights, internal structure and annotations. Where the Image API delivers pixels, the Presentation API is the table of contents that ties those pixels into a coherent, navigable object expressed as a JSON manifest. This guide walks the model end to end with reusable examples, for Presentation API 3.0.

How is a Presentation API document structured?

The model is a small hierarchy of typed resources:

• Collection: a list of Manifests and sub-Collections, your navigable tree.
• Manifest: one object (a book, a map, a file).
• Canvas: one view, a page side or a surface, with its own width/height.
• AnnotationPage / Annotation: place images (painting) and notes (commenting) onto canvases.
• Range: internal structure, chapters, sections, illuminations.

A viewer loads the Manifest URL and renders the whole tree.

How do you build a Collection over many Manifests?

When you have more than one object, group them so users can browse:

{
  "@context": "http://iiif.io/api/presentation/3/context.json",
  "id": "https://example.org/iiif/collection/medieval.json",
  "type": "Collection",
  "label": { "en": ["Medieval Manuscripts"] },
  "items": [
    { "id": "https://example.org/iiif/ms-12/manifest.json", "type": "Manifest",
      "label": { "en": ["Book of Hours, MS 12"] } },
    { "id": "https://example.org/iiif/ms-44/manifest.json", "type": "Manifest",
      "label": { "en": ["Psalter, MS 44"] } }
  ]
}

Each referenced Manifest is still independently usable; the Collection just gives a path through them.

What does behavior control?

behavior is how you give viewers display hints without dictating their UI:

behavior value	Effect in viewers
paged	Show as a book with two-page spreads
individuals	Show each canvas on its own, not paged
continuous	Stitch canvases into one continuous scroll (good for scrolls)
non-paged	Exclude a canvas from page-turning (e.g. a colour bar)

This replaced version 2's viewingHint. A misst behavior is why a scroll renders as awkward facing pages.

How do you express internal structure with Ranges?

A structures array of Ranges turns a flat sequence of canvases into a navigable outline, the equivalent of a table of contents:

"structures": [{
  "id": "https://example.org/iiif/ms-12/range/1",
  "type": "Range",
  "label": { "en": ["Calendar"] },
  "items": [
    { "id": "https://example.org/iiif/ms-12/canvas/1", "type": "Canvas" },
    { "id": "https://example.org/iiif/ms-12/canvas/2", "type": "Canvas" }
  ]
}]

Now a reader can jump straight to "Calendar" instead of scrolling page by page.

How do you handle reading direction and right-to-left scripts?

Set viewingDirection on the Manifest. For Hebrew, Arabic, or Persian material use "right-to-left" so paged viewers open spreads and advance in the correct order. Combine it with behavior: ["paged"] and a canvas order that follows the physical object. Getting this wrong is a common and visible error with non-Latin manuscripts, the pages "turn backwards."

What does a sound end-to-end workflow look like?

1. Inventory your objects and their physical structure (pages, sections).
2. Decide the hierarchy: one Collection over many Manifests.
3. Generate each Manifest from your catalogue, mapping rows to canvases.
4. Add metadata, rights, requiredStatement, behavior, viewingDirection.
5. Add structures (Ranges) for navigation and any commenting annotations.
6. Validate every document with the official Presentation API validator.
7. Publish at stable URLs and load into Mirador or the Universal Viewer to eyeball it.

Key Takeaways

• The Presentation API describes structure and meaning over the Image API's pixels.
• Core resources: Collection, Manifest, Canvas, AnnotationPage/Annotation, Range.
• Use Collections to build a navigable tree across many Manifests.
• behavior gives display hints (paged, continuous, individuals, non-paged).
• Match canvas dimensions to the painted image so annotations land correctly.
• Set viewingDirection for right-to-left scripts, and validate every document.

Frequently Asked Questions

What does the Presentation API describe that the Image API does not?

The Image API serves pixels; the Presentation API describes structure and meaning. It says which canvases make up an object, in what order, with what metadata, ranges, rights and annotations. It is the table of contents over the Image API's pixels.

What are the main resource types?

Collection groups Manifests; Manifest represents one object; Canvas is a single view (a page or surface); AnnotationPage and Annotation place images and notes onto canvases; Range expresses internal structure like chapters.

How do Collections relate to Manifests?

A Collection is a list that can contain Manifests and other Collections, letting you build a navigable tree of your holdings. Each Manifest is still independently addressable and usable on its own.

What is the behavior property for?

behavior carries display hints such as paged, continuous, individuals or non-paged, telling viewers whether to show spreads, a scroll, or single views. It replaced the older viewingHint from version 2.

Do canvas dimensions have to match the image?

The canvas has its own coordinate space, but for a single painted image the canvas width and height should match the image so annotations target correct coordinates. Mismatches misplace every region.

How do I let viewers know reading direction?

Set viewingDirection on the Manifest, for example right-to-left for Hebrew or Arabic manuscripts, so paged viewers open spreads and turn pages in the correct order.

Related reading

• Best Practices to Build IIIF manifests
• How to Understand what IIIF is
• When to Annotate images with IIIF
• Using IIIF for manuscripts
• MODS records for descriptive metadata