Home

IIIF Presentation API 3.0 ALPHA DRAFT

Status of this Document

This Version: 3.0.0-ALPHA

Latest Stable Version: 2.1.1

Previous Version: 2.1.1

Editors

Copyright © 2012-2018 Editors and contributors. Published by the IIIF Consortium under the CC-BY license, see disclaimer.

Status Warning This is a work in progress and may change without any notices. Implementers should be aware that this document is not stable. Implementers are likely to find the specification changing in incompatible ways. Those interested in implementing this document before it reaches beta or release stages should join the mailing list and take part in the discussions, and follow the emerging issues on Github.


Table of Contents

1. Introduction

Access to image-based resources is fundamental to many research disciplines, scholarship and the transmission of cultural knowledge. Digital images are a container for much of the information content in the Web-based delivery of digitized cultural heritage objects. Collections of born-digital images can also benefit from a standardized method to structure their layout and presentation, such as slideshows, image carousels, web comics, and more.

This document describes how the structure and layout of a complex image-based object can be made available in a standard manner. Many different styles of viewer can be implemented that consume the information to enable a rich and dynamic experience, consuming content from across collections and hosting institutions.

An object may comprise a series of pages, surfaces or other views; for example the single view of a painting, the two sides of a photograph, four cardinal views of a statue, or the many pages of an edition of a newspaper or book. The primary requirements for the Presentation API are to provide an order for these views, the resources needed to display a representation of the view, and the descriptive information needed to allow the user to understand what is being seen.

The principles of Linked Data and the Architecture of the Web are adopted in order to provide a distributed and interoperable system. The Shared Canvas data model and JSON-LD are leveraged to create an easy-to-implement, JSON-based format.

Please send feedback to iiif-discuss@googlegroups.com

1.1. Objectives and Scope

The objective of the IIIF (pronounced “Triple-Eye-Eff”) Presentation API is to provide the information necessary to allow a rich, online viewing environment for primarily image-based objects to be presented to a human user, likely in conjunction with the IIIF Image API. This is the sole purpose of the API and therefore the descriptive information is given in a way that is intended for humans to read, but not semantically available to machines. In particular, it explicitly does not aim to provide metadata that would drive discovery of the digitized objects.

The following are within the scope of the current document:

  • The display of digitized images associated with a particular physical object, or born-digital compound object.
  • Navigation between multiple views of the object.
  • The display of text, and resources of other media types, associated with the object views – this includes descriptive information about the object, labels that can aid navigation such as numbers associated with individual pages, copyright or attribution information, etc.

The following are not within scope:

  • The discovery or selection of interesting digitized objects is not directly supported; however hooks to reference further resources are available.
  • Search within the object; which is described by the IIIF Content Search API.

Note that in the following descriptions, “object” (or “physical object”) is used to refer to a physical object that has been digitized or a born-digital compound object, and “resources” refer to the digital resources that are the result of that digitization or digital creation process.

1.2. Motivating Use Cases

There are many different types of digitized or digital compound objects, from ancient scrolls to modern newspapers, from medieval manuscripts to online comics, and from large maps to small photographs. Many of them bear texts, sometimes difficult to read either due to the decay of the physical object or lack of understanding of the script or language. These use cases are described in a separate document.

Collectively the use cases require a model in which one can characterize the object (via the Manifest resource), the order(s) in which individual views are presented (the Sequence resource), and the individual views (Canvas resources). Each Canvas may have images and/or other content resources associated with it (Content resources) to allow the view to be rendered. An object may also have parts; for example, a book may have chapters where several pages may be associated with a single chapter (a Range resource) and there may be groups of objects (Collection resources). These resource types, along with their properties, make up the IIIF Presentation API.

1.3. Terminology

The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in RFC 2119.

2. Resource Type Overview

This section provides an overview of the resource types (or classes) that are used in the specification. They are each presented in more detail in Section 5.

2.1. Basic Types

This specification makes use of the following primary resource types:

Primary Resource Types

Manifest

The overall description of the structure and properties of the digital representation of an object. It carries information needed for the viewer to present the digitized content to the user, such as a title and other descriptive information about the object or the intellectual work that it conveys. Each Manifest describes how to present a single object such as a book, a photograph, or a statue.

Sequence

The order of the views of the object. Multiple Sequences are allowed to cover situations when there are multiple equally valid orders through the content, such as when a manuscript’s pages are rebound or archival collections are reordered.

Canvas

A virtual container that represents a page or view and has content resources associated with it or with parts of it. The Canvas provides a frame of reference for the layout of the content. The concept of a Canvas is borrowed from standards like PDF and HTML, or applications like Photoshop and Powerpoint, where the display starts from a blank display and images, video, text and other resources are “painted” on to it.

Content

Content resources such as images, audio, video or text that are associated with a Canvas.

2.2. Additional Types

Collection

An ordered list of Manifests, and/or further Collections. Collections allow easy navigation among the Manifests in a hierarchical structure, potentially each with its own descriptive information.

AnnotationPage

An ordered list of Annotations in a single response, typically associated with a single Canvas, and can be part of an AnnotationCollection.

Annotation

Content resources and commentary are associated with a Canvas via an Annotation. This provides a single, coherent method for aligning information, and provides a standards based framework for distinguishing parts of resources and parts of Canvases. As Annotations can be added later, it promotes a distributed system in which publishers can align their content with the descriptions created by others.

AnnotationCollection

An ordered list of AnnotationPages. AnnotationCollections allow higher level groupings of Annotations to be recorded. For example, all of the English translation Annotations of a medieval French document could be kept separate from the transcription or an edition in modern French.

Range

An ordered list of Canvases, and/or further Ranges. Ranges allow Canvases, or parts thereof, to be grouped together in some way. This could be for textual reasons, such as to distinguish books, chapters, verses, sections, non-content-bearing pages, the table of contents or similar. Equally, physical features might be important such as quires or gatherings, sections that have been added later and so forth.

3. Resource Properties

This specification defines properties in five distinct areas. Most of the properties may be associated with any of the resource types described above, and may have more than one value. The property relates to the resource that it is associated with, so the label property on a Manifest is the human readable label of the Manifest, whereas the same label property on a Canvas is the human readable label for that particular view. In the descriptions of the properties, the resource that the property is associated with is called “this resource”.

The requirements for which classes have which properties are summarized in Appendix A.

Other properties are allowed, either via custom extensions or endorsed by IIIF. If a client discovers properties that it does not understand, then it must ignore them. Other properties should consist of a prefix and a name in the form “prefix:name” to ensure it does not collide with a property defined by IIIF specifications.

3.1. Descriptive Properties

label

A human readable label, name or title for this resource. The label property is intended to be displayed as a short, textual surrogate for the resource if a human needs to make a distinction between it and similar resources, for example between objects, pages, or options for a choice of images to display.

The value of the property must be a JSON object, as described in the languages section.

  • A Collection must have at least one label.
    Clients must render label on a Collection.
  • A Manifest must have at least one label.
    Clients must render label on a Manifest.
  • A Sequence may have one or more labels, and if there are multiple Sequences in a single Manifest then they must each have at least one label.
    Clients should support multiple Sequences, and if they do, must render label on a Sequence. Clients may render label on a single Sequence.
  • A Canvas should have at least one label.
    Clients must render label on a Canvas, and must generate a label for Canvases that do not have them.
  • A content resource may have one or more labels, and if there is a choice of content resource for the same Canvas, then they should each have at least one label.
    Clients may render label on content resources, and must render them when part of a Choice.
  • A Range should have at least one label.
    Clients must render label on a Range.
  • An AnnotationCollection must have at least one label.
    Clients must render label on an AnnotationCollection.
  • Other resource types may have labels.
    Clients may render label on other resource types.
{"label": {"en": ["Example Object Title"]}}
metadata

A list of descriptive entries to be displayed to the user when they interact with this resource, given as pairs of human readable label and value entries. There are no semantics conveyed by this information, only strings to present to the user when interacting with this resource. A pair might be used to convey information about the creation of the object, a physical description, ownership information, and many other use cases.

The value of the metadata property must be an array of objects, where each object has both label and value properties. The values of both label and value must be JSON objects, as described in the languages section.

  • A Collection should have one or more metadata pairs associated with it.
    Clients must render metadata on a Collection.
  • A Manifest should have one or more metadata pairs associated with it.
    Clients must render metadata on a Manifest.
  • A Canvas may have one or more metadata pairs associated with it.
    Clients should render metadata on a Canvas.
  • Other resource types may have one or more metadata pairs.
    Clients may render metadata on other resource types.

Clients should display the pairs in the order provided. Clients should not use metadata for indexing and discovery purposes, as there are intentionally no consistent semantics. Clients should expect to encounter long texts in the value field, and render them appropriately, such as with an expand button, or in a tabbed interface.

{"metadata": [ {"label": {"en": ["Creator"]}, "value": {"en": ["Anne Artist (1776-1824)"]}} ]}
summary

A short textual summary of this resource, intended to be conveyed to the user when the metadata pairs for the resource are not being displayed. This could be used as a snippet for item level search results, for limited screen real-estate environments, or as an alternative user interface when the metadata fields are not rendered.

The value of the property must be a JSON object, as described in the languages section.

  • A Collection should have one or more summarys.
    Clients should render summary on a Collection.
  • A Manifest should have one or more summmarys. Clients should render summary on a Manifest.
  • A Canvas may have one or more summarys.
    Clients should render summary on a Canvas.
  • Other resource types may have one or more summarys.
    Clients may render summary on other resource types.
{"summary": {"en": ["This is a summary of the object."]}}
thumbnail

An external content resource that represents this resource, such as a small image or short audio clip. It is recommended that a IIIF Image API service be available for images to enable manipulations such as resizing. The same resource may have multiple thumbnails with the same or different type and format.

The value must be a JSON array, with each item in the array being a JSON object that must have an id property and should have at least one of type and format.

  • A Collection should have exactly one thumbnail, and may have more than one.
    Clients should render thumbnail on a Collection.
  • A Manifest should have exactly one thumbnail, and may have more than one.
    Clients should render thumbnail on a Manifest.
  • A Sequence may have one or more thumbnails.
    Clients should render thumbnail on a Sequence.
  • A Canvas may have one or more thumbnails and should have at least one thumbnail if there are multiple resources that make up the representation.
    Clients should render thumbnail on a Canvas.
  • A content resource may have one or more thumbnails and should have at least one thumbnail if it is an option in a Choice of resources.
    Clients should render thumbnail on a content resource.
  • Other resource types may have one or more thumbnails.
    Clients may render thumbnail on other resource types.
{"thumbnail": [{"id": "https://example.org/img/thumb.jpg", "type": "Image"}]}

A date that the client can use for navigation purposes when presenting this resource to the user in a time-based user interface, such as a calendar or timeline. The value must be an xsd:dateTime literal in UTC, expressed in the form “YYYY-MM-DDThh:mm:ssZ”. If the exact time is not known, then “00:00:00” should be used. Similarly, the month or day should be “01” if not known. There must be at most one navDate associated with any given resource. More descriptive date ranges, intended for display directly to the user, should be included in the metadata property for human consumption.

  • A Collection or Manifest may have exactly one navigation date associated with it.
    Clients may render navDate on Collections or Manifests.
  • Other resource types must not have navigation dates.
    Clients should ignore navDate on other resource types.
{"navDate": "2010-01-01T00:00:00Z"}

3.2. Rights and Licensing Properties

The following properties ensure that the interests of the owning or publishing institutions are conveyed regardless of the viewing environment. Given the wide variation of potential client user interfaces, it will not always be possible to display all or any of the properties to the user in the client’s initial state. If initially hidden, the method of revealing them must be obvious, such as a button or scroll bar.

attribution

Text that must be displayed when this resource is displayed or used. For example, the attribution property could be used to present copyright or ownership statements, or simply an acknowledgement of the owning and/or publishing institution.

The value of the property must be a JSON object, as described in the languages section.

  • Any resource type may have one or more attributions.
    Clients must render attribution on every resource type.
{"attribution": {"en": ["Provided courtesy of Example Institution"]}}
rights

A link to an external resource that describes the license or rights statement under which this resource may be used. The rationale for the value being a URI and not a human readable text is that typically there is one license for many resources, and the text is too long to be displayed to the user at the same time as the object. If displaying the text directly to the user is a requirement, then it is recommended to include the information using the attribution property instead, or in metadata.

The value must be an array of JSON objects, each of which must have an id and should have at least one of type and format.

  • Any resource type may have one or more rights statements or licenses associated with it.
    Clients must render rights on every resource type.
{"rights": [{"id": "http://example.org/rights/copyright.html", "type": "Text", "format": "text/html"}]}

A small external image resource that represents an individual or organization associated with this resource. This could be the logo of the owning or hosting institution. The logo must be clearly rendered when the resource is displayed or used, without cropping, rotating or otherwise distorting the image. It is recommended that a IIIF Image API service be available for this image for other manipulations such as resizing.

The value must be an array of JSON objects, each of which must have an id and should have at least one of type and format.

  • Any resource type may have one or more logos associated with it.
    Clients must render logo on every resource type.
{"logo": [{"id": "https://example.org/img/logo.jpg", "type": "Image"}]}

3.3. Technical Properties

id

The URI that identifies this resource. It is recommended that an HTTPS URI be used for all resources. If this resource is only available embedded within another resource, such as a Sequence within a Manifest, then the URI may be the URI of the encapsulating resource with a unique fragment on the end. This is not true for Canvases, which must have their own URI without a fragment.

The value must be a string.

  • A Collection must have exactly one id, and it must be the HTTP(S) URI at which it is published.
    Clients should render id on a Collection.
  • A Manifest must have exactly one id, and it must be the HTTP(S) URI at which it is published.
    Clients should render id on a Manifest.
  • A Sequence may have an id and must not have more than one.
    Clients may render id on a Sequence.
  • A Canvas must have exactly one id, and it must be an HTTP(S) URI. The Canvas’s JSON representation may be published at that URI.
    Clients should render id on a Canvas.
  • A content resource must have exactly one id, and it must be the HTTP(S) URI at which the resource is published.
    Clients may render id on content resources.
  • A Range must have exactly one id, and it must be an HTTP(S) URI.
    Clients may render id on a Range.
  • An AnnotationCollection must have exactly one id, and it must be an HTTP(S) URI.
    Clients may render id on an AnnotationCollection.
  • An AnnotationPage must have exactly one id, and it must be the HTTP(S) URI at which it is published.
    Clients may render id on an AnnotationPage.
  • An Annotation must have exactly one id, and the Annotation’s representation should be published at that URI.
    Clients may render id on an Annotation.
{"id": "https://example.org/iiif/1/manifest"}
type

The type or class of this resource. For types defined by this specification, the value of type will be described in the sections below describing the individual classes. For external resources, the type is drawn from other specifications. Recommendations for basic types such as image, text or audio are given in the table below.

The value must be a string.

  • All resource types must have exactly one type.
    Clients must process, and may render, type on any resource type.
Class Description
Application Software intended to be executed
Dataset Data not intended to be rendered to humans directly
Image Two dimensional visual resources primarily intended to be seen
Sound Auditory resources primarily intended to be heard
Text Resources primarily intended to be read
Video Moving images, with or without accompanying audio
{"type": "Dataset"}
format

The specific media type (often called a MIME type) for this content resource, for example “image/jpeg”. This is important for distinguishing different formats of the same overall type of resource, such as distinguishing text in XML from plain text.

The value must be a string.

  • A content resource should have exactly one format, and if so, it should be the value of the Content-Type header returned when the resource is dereferenced.
    Clients may render the format of any content resource.
  • Other resource types must not have a format.
    Clients should ignore format on other resource types.

Note that this is different to the formats property in the Image API, which gives the extension to use within that API. It would be inappropriate to use in this case, as format can be used with any content resource, not just images.

{"type": "Dataset", "format": "application/xml"}
language

The language or languages used in the content of this external resource. This property is already available from the Web Annotation model for content resources that are the body or target of an Annotation, however it may also be used for resources referenced from related, rendering, rights, and within.

The value must be an array of strings.

  • An external resource may have one or more language values, and each value must be a valid language code, as described under the languages section.
    Clients should process the language of external resources to present the most appropriate content to the user.
  • Other resource types must not have a language.
    Clients should ignore language on other resource types.
{"rendering": [{"id": "http://example.org/docs/doc.pdf", "type": "Text", "format": "application/pdf", "language": ["en"]}]}
profile

A schema or named set of functionality available from this resource. The profile can further clarify the type and/or format of an external resource or service, allowing clients to customize their handling of this resource.

The value must be a string, either taken from the table below or a URI.

  • Services and resources referenced by seeAlso should have exactly one profile. Clients should process the profile of a service or external resource.
  • Other resource types may have exactly one profile. Clients may process the profile of other resource types.
{
  "type": "Dataset",
  "format": "application/xml",
  "profile": "info:srw/schema/1/mods-v3.3"
}
height

The height of this Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the width, it conveys an aspect ratio for the space in which content resources are located.

The value must be a non-negative integer or floating point number.

  • A Canvas should have exactly one height, and must not have more than one. If it has a height, it must also have a width.
    Clients must process, and may render, height on a Canvas.
  • Content resources may have exactly one height, given in pixels, if appropriate.
    Clients should process, and may render, height on content resources.
  • Other resource types must not have a height.
    Clients should ignore height on other resource types.
{"height": 1800}
width

The width of this Canvas or external content resource. For content resources, the value is in pixels. For Canvases, the value does not have a unit. In combination with the height, it conveys an aspect ratio for the space in which content resources are located.

The value must be a non-negative integer or floating point number.

  • A Canvas should have exactly one width, and must not have more than one. If it has a width, it must also have a height.
    Clients must process, and may render, width on a Canvas.
  • Content resources may have exactly one width, given in pixels, if appropriate.
    Clients should process, and may render, width on content resources.
  • Other resource types must not have a width.
    Clients should ignore width on other resource types.
{"width": 1200}
duration

The duration of this Canvas or external content resource, given in seconds.

The value must be a non-negative floating point number.

  • A Canvas may have exactly one duration, and must not have more than one.
    Clients must process, and may render, duration on a Canvas.
  • Content resources may have exactly one duration, and must not have more than one.
    Clients should process, and may render, duration on content resources.
  • Other resource types must not have a duration.
    Clients should ignore duration on other resource types.
{"duration": 125.0}
viewingDirection

The direction that a set of Canvases should be displayed to the user. This specification defines four direction values in the table below. Others may be defined externally and given as a full URI.

The value must be a string, taken from the table below or a full URI.

  • A Collection may have exactly one viewingDirection, and if so, it applies to the order in which its members are rendered.
    Clients should process viewingDirection on a Collection.
  • A Manifest may have exactly one viewingDirection, and if so, it applies to all of its sequences unless the sequence specifies its own value.
    Clients should process viewingDirection on a Manifest.
  • A Sequence may have exactly one viewingDirection.
    Clients should process viewingDirection on a Sequence.
  • A Range may have exactly one viewingDirection.
    Clients may process viewingDirection on a Range.
  • Other resource types must not have a viewingDirection.
    Clients should ignore viewingDirection on other resource types.
Value Description
left-to-right The object is displayed from left to right. The default if not specified.
right-to-left The object is displayed from right to left.
top-to-bottom The object is displayed from the top to the bottom.
bottom-to-top The object is displayed from the bottom to the top.
{"viewingDirection": "left-to-right"}
behavior

A set of user experience features for the client to use when presenting this resource to the user. This specification defines the values specified in the table below. Others may be defined externally, and would be given as a URI.

The value must be an array of strings, taken from the table below or a URI.

  • Any resource type may have one or more features in behavior.
    Clients should process behavior on any resource where it is valid, unless otherwise stated in the table below (e.g. non-paged, facing-pages).
Value Description
individuals Valid on Collection, Manifest, Sequence and Range. For Collections with this behavior, each of the included Manifests are distinct objects. For Manifest, Sequence and Range, the included Canvases are distinct views, and should not be presented in a page-turning interface. This is the default behavior if none are specified.
paged Valid on Manifest, Sequence and Range. Canvases with this behavior represent pages in a bound volume, and should be presented in a page-turning interface if one is available. The first canvas is a single view (the first recto) and thus the second canvas likely represents the back of the object in the first canvas. If this is not the case, see the “non-paged” behavior.
continuous Valid on Manifest, Sequence and Range. A Canvas with this behavior is a partial view and an appropriate rendering might display all of the Canvases virtually stitched together, such as a long scroll split into sections. This behavior has no implication for audio resources. The viewingDirection of the Sequence or Manifest will determine the appropriate arrangement of the Canvases.
multi-part Valid only for Collection. Collections with this behavior consist of multiple Manifests that each form part of a logical whole, such as multi-volume books or a set of journal issues. Clients might render the Collection as a table of contents, rather than with thumbnails.
non-paged Valid only for Canvas. Canvases with this behavior must not be presented in a page turning interface, and must be skipped over when determining the page sequence. This behavior must be ignored if the current Sequence or Manifest does not have the “paged” behavior.
facing-pages Valid only for Canvas. Canvases with this behavior, in a Sequence or Manifest with the “paged” behavior, must be displayed by themselves, as they depict both parts of the opening. If all of the Canvases are like this, then page turning is not possible, so simply use “individuals” instead.
none Valid on AnnotationCollection, AnnotationPage, Annotation, SpecificResource and Choice. If this behavior is provided, then the client should not render the resource by default, but allow the user to turn it on and off.
no-nav Valid only for Range. Ranges with this behavior must not be displayed to the user in a navigation hierarchy. This allows for Ranges to be present that capture unnamed regions with no interesting content.
auto-advance Valid on Collection, Manifest, Sequence and Canvas. When the client reaches the end of a Canvas with a duration dimension that has (or is within a resource that has) this behavior, it should immediately proceed to the next Canvas and render it. If there is no subsequent Canvas in the current context, then this behavior should be ignored. When applied to a Collection, the client should treat the first Canvas of the next Manifest as following the last Canvas of the previous Manifest, respecting any startCanvas specified.
together Valid only for Collection. A client should present all of the child Manifests to the user at once in a separate viewing area with its own controls. Clients should catch attempts to create too many viewing areas. The “together” value should not be interpreted as applying to the members any child resources.
{"behavior": ["auto-advance", "individuals"]}
timeMode

A mode associated with an Annotation that is to be applied to the rendering of any time-based media, or otherwise could be considered to have a duration, used as a body resource of that Annotation. Note that the association of timeMode with the Annotation means that different resources in the body cannot have different values. This specification defines the values specified in the table below. Others may be defined externally, and would be given as a full URI.

The value must be a string, taken from the table below or a full URI.

  • An Annotation may have exactly one timeMode property.
    Clients should process timeMode on an Annotation.
Value Description
trim (default, if not supplied) If the content resource has a longer duration than the duration of portion of the Canvas it is associated with, then at the end of the Canvas’s duration, the playback of the content resource must also end. If the content resource has a shorter duration than the duration of the portion of the Canvas it is associated with, then, for video resources, the last frame should persist on-screen until the end of the Canvas portion’s duration. For example, a video of 120 seconds annotated to a Canvas with a duration of 100 seconds would play only the first 100 seconds and drop the last 20 second.
scale Fit the duration of content resource to the duration of the portion of the Canvas it is associated with by scaling. For example, a video of 120 seconds annotated to a Canvas with a duration of 60 seconds would be played at double-speed.
loop If the content resource is shorter than the duration of the Canvas, it must be repeated to fill the entire duration. Resources longer than the duration must be trimmed as described above. For example, if a 20 second duration audio stream is annotated onto a Canvas with duration 30 seconds, it will be played one and a half times.
{"timeMode": "trim"}

3.4. Linking Properties

A link to an external resource that describes or is about this resource. The external resource must be able to be displayed directly to the user. Examples might include a video or academic paper about the resource, a website, an HTML description, and so forth.

The value must be an array of JSON objects. Each object must have the id, type and label properties, and should have a format property.

  • Any resource type may have one or more external resources related to it.
    Clients should render related on a Collection, Manifest or Canvas, and may render related on other resource types.
{"related": [{
  "id": "https://example.com/info/",
  "type": "Text",
  "label": {"en": ["Related web page"]},
  "format": "text/html"}]}
rendering

A link to an external resource that is an alternative, non-IIIF representation of this resource. The external resource must be able to be displayed directly to a human user, and must not have a splash page or other interstitial resource that mediates access to it. If access control is required, then the IIIF Authentication API is recommended. Examples might include the preferred viewing environment for the IIIF resource, such as a viewer page on the publisher’s web site. Other uses include a rendering of a manifest as a PDF or EPUB with the images and text of the book, or a slide deck with images of the museum object.

The value must be an array of JSON objects. Each object must have the id, type and label properties, and should have a format property.

  • Any resource type may have one or more external rendering resources.
    Clients should render rendering on a Collection, Manifest or Canvas, and may render rendering on other resource types.
{"rendering": [{
  "id": "https://example.org/1.pdf",
  "type": "Text",
  "label": {"en": ["PDF Rendering of Book"]},
  "format": "application/pdf"}]}
service

A link to an external service that the client might interact with directly and gain additional information or functionality for using this resource, such as from an image to the base URI of an associated IIIF Image API service. The service resource should have additional information associated with it in order to allow the client to determine how to make appropriate use of it. Please see the Service Profiles document for currently known service types.

The value must be an array of JSON objects. Each object must have the id and type properties, and should have the label and profile properties.

  • Any resource type may have one or more links to an external service.
    Clients may process service on any resource type, and should process the IIIF Image API service.
{"service": [
  {"id": "https://example.org/service",
   "type": "Service",
   "profile": "http://example.org/docs/service"
  }]}
seeAlso

A link to an external, machine-readable resource that is related to this resource, such as an XML or RDF description. Properties of the external resource should be given to help the client select between multiple descriptions (if provided), and to make appropriate use of the document. If the relationship between the resource and the document needs to be more specific, then the document should include that relationship rather than the IIIF resource. Other IIIF resources, such as a related Manifest, are valid targets for seeAlso. The URI of the document must identify a single representation of the data in a particular format. For example, if the same data exists in JSON and XML, then separate resources should be added for each representation, with distinct id and format properties.

The value must be an array of JSON objects. Each object must have the id and type properties, and should have the label, format and profile properties.

  • Any resource type may have one or more external documents related to it.
    Clients may process seeAlso on any resource type.
{"seeAlso" : [{
    "id": "https://example.org/library/catalog/book1.xml",
    "type": "Dataset",
    "format": "text/xml",
    "profile": "http://example.org/profiles/bibliographic"
  }]}
within

A link to another resource that contains this resource, such as a Manifest that is part of a Collection. When encountering the within property and the referenced resource is not included in the current representation, clients might retrieve the referenced resource to contribute to the processing of this resource. For example, if a Canvas is encountered as a stand alone resource, it might be within a Manifest that includes the Sequence and other contextual information, or a Manifest might be within a Collection, which would aid in navigation.

The value must be an array of JSON objects. Each object must have the id and type properties, and should have the label property.

  • Collections or AnnotationPages that serve as pages must be within exactly one paged resource.
    Clients should render within on a Collection or AnnotationPage.
  • Other resource types, including Collections or AnnotationPages not serving as pages, may be within one or more containing resources.
    Clients may render within on other resource types.
{"within": [{"id": "https://example.org/iiif/1", "type": "Manifest"}]}
startCanvas

A link from this Manifest, Sequence or Range to a Canvas that is contained within it. On seeing this relationship, a client should advance to the specified Canvas when beginning navigation through the Sequence/Range. This allows the client to begin with the first Canvas that contains interesting content rather than requiring the user to skip past blank or empty Canvases manually. The Canvas must be included in the first Sequence embedded within the Manifest.

The value must be a JSON object, which must have the id and type properties.

  • A Manifest, Sequence or Range may have exactly one Canvas as its starting Canvas. Clients should process startCanvas on a Manifest, Sequence or Range.
  • Other resource types must not have a starting Canvas. Clients should ignore startCanvas on other resource types.
{"startCanvas": {"id": "https://example.org/iiif/1/canvas/1", "type": "Canvas"}}
includes

A link from this Range to an AnnotationCollection that includes the Annotations of content resources for the Range. Clients might use this to present content to the user from a different Canvas when interacting with the Range, or to jump to the next part of the Range within the same Canvas.

The value must be a JSON object, which must have the id and type properties, and the type must be AnnotationCollection.

  • A Range may have exactly one includes property.
    Clients may process includes on a Range.
  • Other resource types must not have the includes property.
    Clients should ignore includes on other resource types.
{"includes": {"id": "https://example.org/iiif/1/annos/1", "type": "AnnotationCollection"}}

3.5. Paging Properties

first

A link from this paged resource, such as a Collection or AnnotationCollection, to its first page resource, another Collection or an AnnotationPage respectively.

The value must be a JSON object, which must have the id and type properties, and should have the label property.

  • A Collection may have exactly one Collection as its first page.
    Clients should process, and may render, first on a Collection.
  • An AnnotationCollection may have exactly one AnnotationPage as its first page.
    Clients should process, and may render, first on an AnnotationCollection.
  • Other resource types must not have a first page.
    Clients should ignore first on other resource types.
{"first": {"id": "https://example.org/iiif/1/annos/1", "type": "AnnotationPage"}}
last

A link from this paged resource to its last page resource.

The value must be a JSON object, which must have the id and type properties, and should have the label property.

  • A Collection may have exactly one Collection as its last page.
    Clients may render last on a Collection.
  • An AnnotationCollection may have exactly one AnnotationPage as its last page.
    Clients may render last on an AnnotationCollection.
  • Other resource types must not have a last page.
    Clients should ignore last on other resource types.
{"last": {"id": "https://example.org/iiif/1/annos/23", "type": "AnnotationPage"}}
total

The total number of leaf resources in this paged resource, such as the number of Annotations within an AnnotationCollection.

The value must be a non-negative integer.

  • A Collection may have exactly one total, which must be the total number of Collections and Manifests in its list of pages.
    Clients may render total on a Collection.
  • An AnnotationCollection may have exactly one total, which must be the total number of Annotations in its list of pages.
    Clients may render total on an AnnotationCollection.
  • Other resource types must not have a total.
    Clients should ignore total on other resource types.
{"total": 2217}
next

A link from this page resource to the next page resource that follows it in order.

The value must be a JSON object, which must have the id and type properties, and should have the label property.

  • A Collection may have exactly one Collection as its next page.
    Clients should process, and may render next on a Collection.
  • An AnnotationPage may have exactly one AnnotationPage as its next page.
    Clients should process, and may render next on an AnnotationPage.
  • Other resource types must not have next pages.
    Clients should ignore next on other resource types.
{"next": {"id": "https://example.org/iiif/1/annos/3", "type": "AnnotationPage"}}
prev

A link from this page resource to the previous page resource that precedes it in order.

The value must be a JSON object, which must have the id and type properties, and should have the label property.

  • A Collection may have exactly one Collection as its previous page.
    Clients should process, and may render prev on a Collection.
  • An AnnotationPage may have exactly one AnnotationPage as its previous page.
    Clients should process, and may render prev on an AnnotationPage.
  • Other resource types must not have previous pages.
    Clients should ignore prev on other resource types.
{"prev": {"id": "https://example.org/iiif/1/annos/2", "type": "AnnotationPage"}}
startIndex

The 0 based index of the first included resource in this page resource, relative to the parent paged resource.

The value must be a non-negative integer.

  • A Collection may have exactly one startIndex, which must be the index of its first Collection or Manifest relative to the order established by its parent paging Collection.
    Clients may process or render startIndex on a Collection.
  • An AnnotationPage may have exactly one startIndex, which must be the index of its first Annotation relative to the order established by its parent paging AnnotationCollection.
    Clients may process or render startIndex on an AnnotationPage.
  • Other resource types must not have a startIndex.
    Clients should ignore startIndex on other resource types.
{"startIndex": 300}

3.6. Structural Properties

These properties define the structure of the object being represented in IIIF by allowing the inclusion of child resources within parents, such as a Canvas within a Sequence, or a Manifest within a Collection. The majority of cases use items, however there are two special cases for different sorts of structures.

items

Much of the functionality of the IIIF Presentation API is simply recording the order in which child resources occur within a parent resource, such as Collections or Manifests within a parent Collection, Sequences within a Manifest, or Canvases within a Sequence. All of these situations are covered with a single property, items.

The value must be an array of objects.

  • A Collection must have a list of zero or more Collections and/or Manifests in items.
    Clients must process items on a Collection.
  • A Manifest must have a list of one or more Sequences in items.
    Clients must process items on a Manifest.
  • A Sequence must have a list of one or more Canvases in items.
    Clients must process items on a Sequence.
  • A Canvas should have a list of one or more AnnotationPages in items.
    Clients must process items on a Canvas.
  • An AnnotationPage must have a list of zero or more Annotations in items.
    Clients must process items on an AnnotationPage.
  • A Range must have a list of one or more Ranges and/or Canvases in items.
    Clients should process items on a Range.
{"items": [{ ... }]}
structures

The structure of an object represented as a Manifest can be described using a hierarchy of Ranges. Ranges can be used to describe the “table of contents” of the object or other structures that the user can interact with beyond a simple linear progression described in the Sequence. The hierarchy is built by nesting the child Range resources in the items array of the higher level Range. The top level Ranges of these hierarchies are given in the structures property.

The value must be an array of objects.

  • A Manifest may have a list of one or more Ranges in structures.
    Clients should process structures on a Manifest. The first hierarchy should be presented to the user by default, and further hierarchies should be able to be selected as alternative structures by the user.
{"structures": [
  {
    "id": "https://example.org/iiif/range/1",
    "type": "Range",
    "items": [{ ... }]
  }
]}
annotations

A list of AnnotationPages that contain commentary or other Annotations about this resource, separate from the annotations that are used to paint content on to a Canvas. The motivation of the Annotations must not be “painting” or “transcribing”, and the target of the Annotations must be this resource or part of it.

The value must be an array of objects. Each object must have at least the id and type properties.

  • Any resource type should have a list of one or more AnnotationPages in content.
    Clients should process annotations on any resource.
{"annotations": [
  {
    "id": "https://example.org/iiif/annotationPage/1",
    "type": "AnnotationPage",
    "items": [{ ... }]
  }
]}

4. JSON-LD Considerations

This section describes features applicable to all of the Presentation API content. For the most part, these are features of the JSON-LD specification that have particular uses within the API and recommendations about URIs to use.

4.1. HTTPS URI Scheme

It is strongly recommended that all URIs use the HTTPS scheme, and be available via that protocol. All URIs must be either HTTPS or HTTP, abbreviated to “HTTP(S)” in this specification.

4.2. URI Representation

Resource descriptions should be embedded within higher-level descriptions, and may also be available via separate requests from HTTP(S) URIs linked in the responses. These URIs are in the id property for the resource. Links to resources must be given as a JSON object with the id property and at least one other property, typically either type, format or profile to give a hint as to what sort of resource is being referred to. Other URI schemes may be used if the resource is not able to be retrieved via HTTP(S).

{
  "thumbnail": [
    {"id": "https://example.org/images/thumb1.jpg", "type": "Image"}
  ]
}

4.3. Repeatable Properties

Any of the properties in the API that can have multiple values must always be given as an array of values, even if there is only a single item in that array.

{
  "seeAlso": [
    {"id": "https://example.org/images/thumb1.jpg", "type": "Image"},
    {"id": "https://example.org/videos/thumb1.pmg", "type": "Video"}   
  ]
}

4.4. Language of Property Values

Language may be associated with strings that are intended to be displayed to the user for the label, summary, attribution fields, plus the label and value fields of the metadata construction.

The values of these fields must be JSON objects, with the keys being the RFC 5646 language code for the language, or if the language is either not known or the string does not have a language, then the key must be "@none". The associated values must be arrays of strings, where each string is the content in the given language.

{"label": {
    "en": ["Whistler's Mother",
           "Arrangement in Grey and Black No. 1: The Artist's Mother"],
    "fr": ["Arrangement en gris et noir no 1",
           "Portrait de la mère de l'artiste",
           "La Mère de Whistler"],
    "@none": ["Whistler (1871)"]
  }
}

Note that RFC 5646 allows the script of the text to be included after a hyphen, such as ar-latn, and clients should be aware of this possibility. This allows for full internationalization of the user interface components described in the response, as the labels as well as values may be translated in this manner; examples are given below.

In the case where multiple values are supplied, clients must use the following algorithm to determine which values to display to the user.

  • If all of the values are in the @none list, treated as not having a language associated with them, the client must display all of those values.
  • Else, the client should try to determine the user’s language preferences, or failing that use some default language preferences. Then:
    • If any of the values have a language associated with them, the client must display all of the values associated with the language that best matches the language preference.
    • If all of the values have a language associated with them, and none match the language preference, the client must select a language and display all of the values associated with that language.
    • If some of the values have a language associated with them, but none match the language preference, the client must display all of the values that do not have a language associated with them.

Note that this does not apply to embedded textual bodies in Annotations, which use the Web Annotation pattern of value and langauge as separate properties.

4.5. HTML Markup in Property Values

Minimal HTML markup may be included in the summary, attribution properties and the value property of a label/value pair in metadata. It must not be used in label or other properties. This is included to allow manifest creators to add links and simple formatting instructions to blocks of text. The content must be well-formed XML and therefore must be wrapped in an element such as p or span. There must not be whitespace on either side of the HTML string, and thus the first character in the string must be a ‘<’ character and the last character must be ‘>’, allowing a consuming application to test whether the value is HTML or plain text using these. To avoid a non-HTML string matching this, it is recommended that an additional whitespace character be added to the end of the value in situations where plain text happens to start and end this way.

In order to avoid HTML or script injection attacks, clients must remove:

  • Tags such as script, style, object, form, input and similar.
  • All attributes other than href on the a tag, src and alt on the img tag.
  • CData sections.
  • XML Comments.
  • Processing instructions.

Clients should allow only a, b, br, i, img, p, small, span, sub and sup tags. Clients may choose to remove any and all tags, therefore it should not be assumed that the formatting will always be rendered.

{"summary": {"en-latn": ["<p>Short <b>summary</b> of the resource.</p>"]}}

4.6. Linked Data Context and Extensions

The top level resource in the response must have the @context property, and it should appear as the very first key/value pair of the JSON representation. This tells Linked Data processors how to interpret the information. The IIIF Presentation API context, below, must occur exactly once per response, and be omitted from any embedded resources. For example, when embedding a sequence without any extensions within a manifest, the sequence must not have the @context field.

The value of the @context property must be a list, and the last two values must be the Web Annotation context and the Presentation API context, in that order. And further contexts must be added at the beginning of the list.

{"@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ]
}

Any additional fields beyond those defined in this specification or the Web Annotation Data Model should be mapped to RDF predicates using further context documents. If possible, these extensions should be added to the top level @context field, and must be added before the above contexts. The JSON-LD 1.1 functionality of type and predicate specific context definitions should be used if possible to try to minimize any cross-extension collisions.

The JSON representation must not include the @graph key at the top level. This key might be created when serializing directly from RDF data using the JSON-LD compaction algorithm. Instead, JSON-LD framing and/or custom code should be used to ensure the structure of the document is as described by this specification.

Embedded JSON-LD data that uses a JSON-LD version 1.0 context definition, such as references to older external services or extensions, may require the context to be included within the service description, rather than listed in the top resource. Care should be taken to use the mappings defined by those contexts, especially with regard to id versus @id, and type versus @type, to ensure that clients receive the keys that they are expecting to process.

5. Resource Structure

This section provides detailed description of the resource types used in this specification. Section 2 provides an overview of the resource types and figures illustrating allowed relationships between them, and Appendix A provides summary tables of the property requirements.

5.1. Manifest

The Manifest resource typically represents a single object and any intellectual work or works embodied within that object. In particular it includes the descriptive, rights and linking information for the object. It then embeds the Sequence(s) of Canvases that should be rendered to the user. The Manifest response contains sufficient information for the client to initialize itself and begin to display something quickly to the user.

The identifier in id must be able to be dereferenced to retrieve the JSON description of the Manifest, and thus must use the HTTP(S) URI scheme.

Along with the descriptive information, there is an items section, which is a list of JSON-LD objects. Each object describes a Sequence, discussed in the next section, that represents the order of the parts of the work, each represented by a Canvas. There must be at least one Sequence, and the first Sequence must be included within the Manifest as well as optionally being available from its own URI. Subsequent Sequences may be embedded within the Manifest, or referenced with their identifier (id), class (type) and label (label).

There may also be a structures section listing one or more Ranges which describe additional structure of the content, such as might be rendered as a table of contents.

Finally, the Manifest may have an annotations list, which includes AnnotationPage resources where the Annotations are have the Manifest as their target. These will typically be comment style annotations, and must not have painting as their motivation. The annotations property may also be found on any other resource type with these same restrictions.

The example below includes only the Manifest-level information, however actual implementations must embed at least the first Sequence, Canvas and content information.

{
  // Metadata about this manifest file
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "https://example.org/iiif/book1/manifest",
  "type": "Manifest",

  // Descriptive metadata about the object/work
  "label": {"en": ["Book 1"]},
  "metadata": [
    {"label": {"en": ["Author"]},
     "value": {"@none": ["Anne Author"]}},
    {"label": {"en": ["Published"]},
     "value": {
        "en": ["Paris, circa 1400"],
        "fr": ["Paris, environ 1400"]}
    },
    {"label": {"en": ["Notes"]},
     "value": {"en": ["Text of note 1", "Text of note 2"]}},
    {"label": {"en": ["Source"]},
     "value": {"@none": ["<span>From: <a href=\"http://example.org/db/1.html\">Some Collection</a></span>"]}}
  ],
  "summary": {"en": ["Book 1, written be Anne Author, published in Paris around 1400."]},

  "thumbnail": [{
    "id": "https://example.org/images/book1-page1/full/80,100/0/default.jpg",
    "type": "Image",
    "service": {
      "id": "https://example.org/images/book1-page1",
      "type": "ImageService3",
      "profile": "level1"
    }
  }],

  // Presentation Information
  "viewingDirection": "right-to-left",
  "behavior": ["paged"],
  "navDate": "1856-01-01T00:00:00Z",

  // Rights Information
  "rights": [{
    "id":"http://example.org/license.html",
    "type": "Text",
    "language": "en",
    "format": "text/html"}],
  "attribution": {"en": ["Provided by Example Organization"]},
  "logo": {
    "id": "https://example.org/logos/institution1.jpg",
    "service": {
        "id": "https://example.org/service/inst1",
        "type": "ImageService3",
        "profile": "level2"
    }
  },

  // Links
  "related": [{
    "id": "https://example.org/videos/video-book1.mpg",
    "type": "Video",
    "label": {"en":["Video discussing this book"]},
    "format": "video/mpeg"
  }],
  "service": [{
    "id": "https://example.org/service/example",
    "type": "Service",
    "profile": "http://example.org/docs/example-service.html"
  }],
  "seeAlso": [{
    "id": "https://example.org/library/catalog/book1.xml",
    "type": "Dataset",
    "format": "text/xml",
    "profile": "http://example.org/profiles/bibliographic"
  }],
  "rendering": [{
    "id": "http://example.org/iiif/book1.pdf",
    "type": "Text",
    "label": {"en": ["Download as PDF"]},
    "format": "application/pdf"
  }],
  "within": [{
    "id": "http://example.org/collections/books/",
    "type": "Collection"
  }],
  "startCanvas": {
    "id": "http://example.org/iiif/book1/canvas/p2",
    "type": "Canvas"
  },

  // List of Sequences
  "items": [
      {
        "id": "http://example.org/iiif/book1/sequence/normal",
        "type": "Sequence",
        "label": {"en": ["Current Page Order"]}
        // Sequence's page order should be included here
      }
      // Any additional Sequences can be included or linked here
  ],

  // structure of the resource, described with Ranges
  "structure": [
    {
      "id": "http://example.org/iiif/book1/range/top",
      "type": "Range"
      // Ranges members should be included here
    }
    // Any additional top level Ranges can be included here
  ],

  // Commentary Annotations on the Manifest
  "annotations": [
    {
      "id": "http://example.org/iiif/book1/annotations/p1",
      "type": "AnnotationPage",
      "items": [
        // Annotations about the Manifest are included here
      ]
    }
  ]
}

5.2. Sequence

The Sequence conveys the ordering of the views of the object. The default Sequence (and typically the only Sequence) must be embedded within the Manifest as the first object in the items property, and may also be available from its own URI. This Sequence should have a URI to identify it. Any additional Sequences may be included, or referenced externally from the Manifest. References to external Sequences must include an id and type, should have a label, and must not have an items property. The description of the Sequence must be available by dereferencing the HTTP(S) URI in id.

Sequences may have their own descriptive, rights and linking metadata using the same fields as for Manifests. The label property may be given for Sequences and must be given if there is more than one referenced from a Manifest. After the metadata, the set of views of the object, represented by Canvas resources, must be listed in order in the items property. There must be at least one Canvas given.

{
  // Metadata about this sequence
  "id": "http://example.org/iiif/book1/sequence/normal",
  "type": "Sequence",
  "label": {"en": ["Current Page Order"]},

  "viewingDirection": "left-to-right",
  "behavior": ["paged"],
  "startCanvas": "http://example.org/iiif/book1/canvas/p2",

  // The order of the canvases
  "items": [
    {
      "id": "http://example.org/iiif/book1/canvas/p1",
      "type": "Canvas",
      "label": {"@none": ["p. 1"]}
      // ...
    },
    {
      "id": "http://example.org/iiif/book1/canvas/p2",
      "type": "Canvas",
      "label": {"@none": ["p. 2"]}
      // ...
    },
    {
      "id": "http://example.org/iiif/book1/canvas/p3",
      "type": "Canvas",
      "label": {"@none": ["p. 3"]}
      // ...
    }
  ]
}

5.3. Canvas

The Canvas represents an individual page or view and acts as a central point for laying out the different content resources that make up the display. Canvases must be identified by a URI and it must be an HTTP(S) URI. The URI of the canvas must not contain a fragment (a # followed by further characters), as this would make it impossible to refer to a segment of the Canvas’s area using the #xywh= syntax. Canvases may be able to be dereferenced separately from the Manifest via their URIs as well as being embedded within the Sequence.

Every Canvas should have a label to display. If one is not provided, the client should automatically generate one for use based on the Canvas’s position within the current Sequence.

Content resources are associated with the Canvas via Web Annotations. Content that is to be rendered as part of the Canvas must be associated by an Annotation with the “painting” motivation. These Annotations are recorded in the items of one or more AnnotationPages, referred to in the items array of the Canvas. If, according to the organization providing the Manifest, clients should render the Annotation quickly then it should be embedded within the Manifest directly. Other AnnotationPages can be referenced with just their id, type and optionally a label, and clients should dereference these pages to discover further content. Content in this case includes media assets such as images, video and audio, textual transcriptions or editions of the Canvas, as well as commentary about the object represented by the Canvas. These different uses may be split up across different AnnotationPages.

A Canvas must have a rectangular aspect ratio (described with the height and width properties) and/or a duration to provide an extent in time. These dimensions allow resources to be associated with specific regions of the Canvas, within the space and/or time extents provided. Content must not be associated with space or time outside of the Canvas’s dimensions, such as at coordinates below 0,0, greater than the height or width, before 0 seconds, or after the duration. Content resources that have dimensions which are not defined for the Canvas must not be associated with that Canvas. For example, it is valid to use a “painting” Annotation to associate an Image (which has only height and width) with a Canvas that has all three dimensions, but it is an error to associate a Video resource (which has height, width and duration) with a Canvas that does not have all three dimensions. Such a resource should instead be referenced with the rendering property, or by Annotations with a motivation other than “painting” in the annotations property.

Parts of Canvases are still Canvases and have a type of “Canvas”. Parts of Canvases can be referenced from Ranges, Annotations or the start property. Spatial parts of Canvases, when referenced from outside an Annotation, must be rectangular and are described by appending an xywh= fragment to the end of the Canvas’s URI. Similarly, temporal parts of Canvases must be described by appending a t= fragment to the end of the Canvas’s URI. Spatial and temporal fragments may be combined, using an & character between them, and the temporal dimension should come first. It is an error to select a region using a dimension that is not defined by the Canvas, such as a temporal region of a Canvas that only has height and width dimensions.

Renderers must scale content into the space represented by the Canvas, and should follow any timeMode value provided for time-based media. If the Canvas represents a view of a physical object, the spatial dimensions of the Canvas should be the same scale as that physical object, and images should depict only the object.

{
  // Metadata about this canvas
  "id": "http://example.org/iiif/book1/canvas/p1",
  "type": "Canvas",
  "label": {"@none": ["p. 1"]},
  "height": 1000,
  "width": 750,
  "duration": 180.0,

  "items": [
    {
      "id": "http://example.org/iiif/book1/page/p1/1",
      "type": "AnnotationPage",
      "items": [
        // Content Annotations on the Canvas are included here
      ]
    }
  ]
}

5.4. Annotation Pages

Association of images and other content with their respective Canvases is done via Annotations. Traditionally Annotations are used for associating commentary with the resource the Annotation’s text or body is about, the Web Annotation model allows any resource to be associated with any other resource, or parts thereof, and it is reused for both commentary and painting resources on the Canvas. Other resources beyond images might include the full text of the object, musical notations, musical performances, diagram transcriptions, commentary annotations, tags, video, data and more.

These Annotations are collected together in AnnotationPage resources, which are included in the items list from the Canvas. Each AnnotationPage can be embedded in its entirety, if the Annotations should be processed as soon as possible when the user navigates to that Canvas, or a reference to an external page. This reference must include id and type, must not include items and may include other properties, such as behavior. All of the Annotations in the AnnotationPage should have the Canvas as their target. Embedded AnnotationPages should be processed by the client first, before externally referenced pages.

The AnnotationPage must have an HTTP(S) URI given in id, and the JSON representation must be returned when that URI is dereferenced. They may have any of the other fields defined in this specification, or the Web Annotation specification. The Annotations are listed in an items list of the AnnotationPage.

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/book1/annopage/p1",
  "type": "AnnotationPage",

  "items": [
    {
      "id": "http://example.org/iiif/book1/annopage/p1/a1",
      "type": "Annotation"
      // ...
    },
    {
      "id": "http://example.org/iiif/book1/annopage/p1/a2",
      "type": "Annotation"
      // ...
    }
  ]
}

5.5. Annotations

Annotations follow the Web Annotation data model. The description provided here is a summary plus any IIIF specific requirements. It must be noted that the W3C standard is the official documentation.

Annotations must have their own HTTP(S) URIs, conveyed in the id property. The JSON-LD description of the Annotation should be returned if the URI is dereferenced, according to the Web Annotation Protocol.

Annotations that associate content that is part of the representation of the view must have the motivation field and the value must be “painting”. This is in order to distinguish it from commentary style Annotations. Text may be thus either be associated with the Canvas via a “painting” annotation, meaning the content is part of the representation, or with another motivation, meaning that it is somehow about the view.

The content resource is linked in the body of the Annotation. The content resource must have an id field, with the value being the URI at which it can be obtained. If a IIIF Image service is available for an image, then the URI must be the complete URI to a particular size of the image content, such as http://example.org/image1/full/1000,/0/default.jpg. It must have a type of “Image”. Its media type may be listed in format, and its height and width may be given as integer values for height and width respectively. The image then should have the service referenced from it.

Although it might seem redundant, the URI of the Canvas must be repeated in the target field of the Annotation. This is to ensure consistency with Annotations that target only part of the resource, described in more detail below, and to remain faithful to the Web Annotation specification, where target is mandatory.

The type of the content resource must be included, and should be taken from the table listed under the definition of type. The format of the resource should be included and, if so, should be the media type that is returned when the resource is dereferenced. The content resources may also have any of the other fields defined in this specification, including commonly label, summary, metadata, license and attribution.

Additional features of the Web Annotation data model may also be used, such as selecting a segment of the Canvas or content resource, or embedding the comment or transcription within the Annotation. The use of these advanced features sometimes results in situations where the target is not a content resource, but instead a SpecificResource, a Choice, or other non-content object. Implementations should check the type of the resource and not assume that it is always content to be rendered.

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/book1/annotation/p0001-image",
  "type": "Annotation",
  "motivation": "painting",
  "body": {
    "id": "http://example.org/iiif/book1/res/page1.jpg",
    "type": "Image",
    "format": "image/jpeg",
    "service": {
      "id": "http://example.org/images/book1-page1",
      "type": "ImageService3",
      "profile": "level2"
    },
    "height":2000,
    "width":1500
  },
  "target": "http://example.org/iiif/book1/canvas/p1"
}

5.6. Range

Ranges are used to represent structure within an object beyond the overall Sequence, such as newspaper sections or articles, chapters within a book, or movements within a piece of music. Ranges can include Canvases, parts of Canvases, or other Ranges, creating a tree structure like a table of contents.

The intent of adding a Range to the Manifest is to allow the client to display a hierarchical navigation interface to enable the user to quickly move through the object’s content. Clients should present only Ranges with the label property and without the “no-nav” behavior to the user. Clients should not render Canvas labels as part of the navigation, and a Range that wraps the Canvas must be created if this is the desired presentation.

Ranges must have URIs and they should be HTTP(S) URIs. Top level Ranges are embedded or externally referenced within the Manifest in a structures property. These top level Ranges then embed other Ranges, Canvases or parts of Canvases in the items property. Each entry in the items field must be a JSON object, and it must have the id and type properties. If a top level Range needs to be dereferenced by the client, then it must not have the items property, such that clients are able to recognize that it should be retrieved in order to be processed.

All of the Canvases or parts that should be considered as being part of a Range must be included within the Range’s items list, or a descendant Range’s items.

The Canvases and parts of Canvases need not be contiguous or in the same order as in any Sequence. Examples include newspaper articles that are continued in different sections, a chapter that starts half way through a page, or time segments of a single canvas that represent different sections of a piece of music.

Ranges may link to an AnnotationCollection that has the content of the Range using the includes property. The referenced AnnotationCollection will contain Annotations that target areas of Canvases within the Range and link content resources to those Canvases.

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/book1/manifest",
  "type": "Manifest",
  // Metadata here ...

  "sequences": [
    // Sequences here ...
  ],

  "structures": [
    {
      "id": "http://example.org/iiif/book1/range/r0",
      "type": "Range",
      "label": {"en": ["Table of Contents"]},
      "items": [
        {
          "id": "http://example.org/iiif/book1/canvas/cover",
          "type": "Canvas"
        },
        {
          "id": "http://example.org/iiif/book1/range/r1",
          "type": "Range",
          "label": {"en": ["Introduction"]},
          "includes": "http://example.org/iiif/book1/annocoll/introTexts",
          "items": [
            {
              "id": "http://example.org/iiif/book1/canvas/p1",
              "type": "Canvas"
            },
            {
              "id": "http://example.org/iiif/book1/canvas/p2",
              "type": "Canvas"
            },
            {
              "id": "http://example.org/iiif/book1/canvas/p3#xywh=0,0,750,300",
              "type": "Canvas"
            }  
          ]
        },
        {
          "id": "http://example.org/iiif/book1/canvas/backCover",
          "type": "Canvas"
        }
      ]
    }
  ]
}

5.7. AnnotationCollection

AnnotationCollections represent groupings of AnnotationPages that should be managed as a single whole, regardless of which Canvas or resource they target. This allows, for example, all of the Annotations that make up a particular translation of the text of a book to be collected together. A client might then present a user interface that allows all of the Annotations in an AnnotationCollection to be displayed or hidden according to the user’s preference.

AnnotationCollections must have a URI, and it should be an HTTP URI. They must have a label and may have any of the other descriptive, linking or rights properties.

{
  "@context": [],
  "id": "http://example.org/iiif/book1/annopage/l1",
  "type": "AnnotationPage",
  "partOf": {
    "id": "http://example.org/iiif/book1/annocoll/transcription",
    "type": "AnnotationCollection",
    "label": {"en": ["Diplomatic Transcription"]}
  }
}

// …

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/book1/annocoll/transcription",
  "type": "AnnotationCollection",
  "label": {"en": ["Diplomatic Transcription"]},

  "first": {"id": "http://example.org/iiif/book1/annopage/l1", "type": "AnnotationPage"},
  "last": {"id": "http://example.org/iiif/book1/annopage/l120", "type": "AnnotationPage"}
}

5.8. Collection

Collections are used to list the manifests available for viewing, and to describe the structures, hierarchies or curated collections that the objects are part of. Collections may include both other Collections and Manifests, in order to form a tree-structured hierarchy.

Collection objects may be embedded inline within other collection objects, such as when the collection is used primarily to subdivide a larger one into more manageable pieces, however manifests must not be embedded within collections. An embedded collection should also have its own URI from which the description is available.

Manifests or Collections may appear within more than one collection. For example, an institution might define four collections: one for modern works, one for historical works, one for newspapers and one for books. The manifest for a modern newspaper would then appear in both the modern collection and the newspaper collection. Alternatively, the institution may choose to have two separate newspaper collections, and reference each as a sub-collection of modern and historical.

The intended usage of collections is to allow clients to:

  • Load a pre-defined set of manifests at initialization time.
  • Receive a set of manifests, such as search results, for rendering.
  • Visualize lists or hierarchies of related manifests.
  • Provide navigation through a list or hierarchy of available manifests.

An empty collection, with no member resources, is allowed but discouraged.

An example collection document:

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/collection/top",
  "type": "Collection",
  "label": {"en": ["Top Level Collection for Example Organization"]},
  "summary": {"en": ["Short summary of the Collection"]},
  "behavior": ["top"],
  "attribution": {"en": ["Provided by Example Organization"]},

  "items": []

}

5.9. Paging

In some situations, AnnotationPage resources or the list of manifests in a collection may be very long or expensive to create. The latter case is especially likely to occur when responses are generated dynamically. In these situations the server may break up the response using paging properties. The length of a response is left to the server’s discretion, but the server should take care not to produce overly long responses that would be difficult for clients to process.

When breaking a response into pages, the paged resource must link to the first page resource, and must not include the items property.

The linked page resource should refer back to the containing paged resource using within. If there is a page resource that follows it (the next page), then it must include a next link to it. If there is a preceding page resource, then it should include a prev link to it.

The paged resource may use the total property to list the total number of leaf resources that are contained within its pages. This would be the total number of annotations in a AnnotationCollection, or the total number of manifests in a collection. Conversely, the page resources may include the startIndex property with index of the first resource in the page, counting from zero relative to the containing paged resource.

The linked page resources may have different properties from the paged resource, including different rights and descriptive properties. Clients must take into account any requirements derived from these properties, such as displaying logo or attribution.

Example Paged AnnotationCollection

An AnnotationCollection representing a long transcription with almost half a million annotations, perhaps where each annotation paints a single word on the canvas:

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/book1/annocoll/transcription",
  "type": "AnnotationCollection",
  "label": {"en": ["Example Long Transcription"]},

  "total": 496923,
  "first": "http://example.org/iiif/book1/annopage/l1"
}

And the corresponding first AnnotationPage:

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/book1/annopage/l1",
  "type": "AnnotationPage",

  "startIndex": 0,
  "within": "http://example.org/iiif/book1/annocoll/transcription",
  "next": "http://example.org/iiif/book1/annopage/l2",

  "resources": [
    // Annotations live here ...
  ]
}

Note that it is still expected that canvases will link directly to the AnnotationPage resources. For example, a particular canvas might refer to the first two AnnotationPage resources within an AnnotationCollection:

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/book1/canvas/c1",
  "type": "Canvas",

  "height": 1000,
  "width": 1000,
  "label": {"en": ["Page 1"]},

  "otherContent": [
    "http://example.org/iiif/book1/annopage/l1",
    "http://example.org/iiif/book1/annopage/l2"
  ]
}
Example Paged Collection

An example large collection with some 9.3 million objects in it:

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/collection/top",
  "type": "Collection",
  "label": {"en": ["Example Big Collection"]},

  "total": 9316290,
  "first": "http://example.org/iiif/collection/c1"
}

And the corresponding first page of manifests:

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/collection/c1",
  "type": "Collection",

  "within": "http://example.org/iiif/collection/top",
  "startIndex": 0,
  "next": "http://example.org/iiif/collection/c2",

  "manifests": [
    // Manifests live here ...
  ]
}

6. HTTP Requests and Responses

This section describes the recommended request and response interactions for the API. The REST and simple HATEOAS approach is followed where an interaction will retrieve a description of the resource, and additional calls may be made by following links obtained from within the description. All of the requests use the HTTP GET method; creation and update of resources is not covered by this specification.

6.1 URI Recommendations

While any URI is technically acceptable for any of the resources in the API, there are several best practices for designing the URIs for the resources.

  • The URI should use the HTTPS scheme, not HTTP.
  • The URI should not include query parameters or fragments.
  • Once published, they should be as persistent and unchanging as possible.
  • Special characters must be encoded.

6.2. Requests

Clients must not attempt to construct resource URIs by themselves, instead they must follow links from within retrieved descriptions or elsewhere.

6.3. Responses

The format for all responses is JSON, as described above. The different requirements for which resources must provide a response is summarized in Appendix A. While some resources do not require their URI to provide the description, it is good practice if possible.

The HTTP Content-Type header of the response should have the value “application/ld+json” (JSON-LD) with the profile parameter given as the context document: http://iiif.io/api/presentation/3/context.json.

Content-Type: application/ld+json;profile="http://iiif.io/api/presentation/3/context.json"

If this cannot be generated due to server configuration details, then the content-type must instead be application/json (regular JSON), without a profile parameter.

Content-Type: application/json

The HTTP server must follow the CORS requirements to enable browser-based clients to retrieve the descriptions. In particular, the response must include the Access-Control-Allow-Origin header, and the value should be *.

Access-Control-Allow-Origin: *

Responses should be compressed by the server as there are significant performance gains to be made for very repetitive data structures.

Recipes for enabling CORS, conditional Content-Type headers and other technical details are provided in the Apache HTTP Server Implementation Notes.

7. Authentication

It may be necessary to restrict access to the descriptions made available via the Presentation API. As the primary means of interaction with the descriptions is by web browsers using XmlHttpRequests across domains, there are some considerations regarding the most appropriate methods for authenticating users and authorizing their access. The approach taken is described in the Authentication specification, and requires requesting a token to add to the requests to identify the user. This token might also be used for other requests defined by other APIs.

It is possible to include Image API service descriptions within the manifest, and within those it is also possible to include links to the Authentication API’s services that are needed to interact with the image content. The first time an Authentication API service is included within a manifest, it must be the complete description. Subsequent references should be just the URI of the service, and clients are expected to look up the details from the full description by matching the URI. Clients must anticipate situations where the Authentication service description in the manifest is out of date: the source of truth is the Image Information document, or other system that references the Authentication API services.

Appendices

A. Summary of Metadata Requirements

Field Meaning
required Required
recommended Recommended
optional Optional
not allowed Not Allowed

Descriptive and Rights Properties

  label metadata summary thumbnail attribution license logo
Collection required recommended recommended recommended optional optional optional
Manifest required recommended recommended recommended optional optional optional
Sequence optional optional optional optional optional optional optional
Canvas required optional optional recommended optional optional optional
Annotation optional optional optional optional optional optional optional
AnnotationPage optional optional optional optional optional optional optional
Range required optional optional optional optional optional optional
AnnotationCollection required optional optional optional optional optional optional
Image Content optional optional optional optional optional optional optional
Other Content optional optional optional optional optional optional optional

Technical Properties

  id type format height width viewingDirection behavior navDate
Collection required required not allowed not allowed not allowed not allowed optional optional
Manifest required required not allowed not allowed not allowed optional optional optional
Sequence optional required not allowed not allowed not allowed optional optional not allowed
Canvas required required not allowed required required not allowed optional not allowed
Annotation recommended required not allowed not allowed not allowed not allowed optional not allowed
AnnotationPage required required not allowed not allowed not allowed not allowed optional not allowed
Range required required not allowed not allowed not allowed optional optional not allowed
AnnotationCollection required required not allowed not allowed not allowed optional optional not allowed
Image Content required required optional recommended recommended not allowed optional not allowed
Other Content required required optional optional optional not allowed optional not allowed

Linking Properties

  seeAlso service related rendering within startCanvas
Collection optional optional optional optional optional not allowed
Manifest optional optional optional optional optional not allowed
Sequence optional optional optional optional optional optional
Canvas optional optional optional optional optional not allowed
Annotation optional optional optional optional optional not allowed
AnnotationPage optional optional optional optional optional not allowed
Range optional optional optional optional optional optional
AnnotationCollection optional optional optional optional optional not allowed
Image Content optional optional optional optional optional not allowed
Other Content optional optional optional optional optional not allowed

Paging Properties

  first last total next prev startIndex
Collection optional optional optional optional optional optional
Manifest not allowed not allowed not allowed not allowed not allowed not allowed
Sequence not allowed not allowed not allowed not allowed not allowed not allowed
Canvas not allowed not allowed not allowed not allowed not allowed not allowed
Annotation not allowed not allowed not allowed not allowed not allowed not allowed
AnnotationPage not allowed not allowed not allowed optional optional optional
Range not allowed not allowed not allowed not allowed not allowed not allowed
AnnotationCollection optional optional optional not allowed not allowed not allowed
Image Content not allowed not allowed not allowed not allowed not allowed not allowed
Other Content not allowed not allowed not allowed not allowed not allowed not allowed

Structural Properties

  collections manifests members sequences structures canvases resources otherContent images ranges
Collection optional optional optional not allowed not allowed not allowed not allowed not allowed not allowed not allowed
Manifest not allowed not allowed not allowed required optional not allowed not allowed not allowed not allowed not allowed
Sequence not allowed not allowed not allowed not allowed not allowed required not allowed not allowed not allowed not allowed
Canvas not allowed not allowed not allowed not allowed not allowed not allowed not allowed optional optional not allowed
Annotation not allowed not allowed not allowed not allowed not allowed not allowed not allowed not allowed not allowed not allowed
AnnotationPage not allowed not allowed not allowed not allowed not allowed not allowed optional not allowed not allowed not allowed
Range not allowed not allowed optional not allowed not allowed optional not allowed not allowed not allowed optional
AnnotationCollection not allowed not allowed not allowed not allowed not allowed not allowed not allowed optional not allowed not allowed
Image Content not allowed not allowed not allowed not allowed not allowed not allowed not allowed not allowed not allowed not allowed
Other Content not allowed not allowed not allowed not allowed not allowed not allowed not allowed not allowed not allowed not allowed

Protocol Behavior

  id is dereferenceable
Collection required
Manifest required
Sequence optional
Canvas recommended
Annotation recommended
AnnotationPage required
Range optional
AnnotationCollection optional
Image Content required
Other Content required

B. Example Manifest Response

Rebuild the example

C. Versioning

Starting with version 2.0, this specification follows Semantic Versioning. See the note Versioning of APIs for details regarding how this is implemented.

D. Acknowledgements

Many thanks to the members of the IIIF for their continuous engagement, innovative ideas and feedback.

E. Change Log

Date Description
XXXX-YY-ZZ Version 3.0
2017-06-09 Version 2.1.1 View change log
2016-05-12 Version 2.1 (Hinty McHintface) View change log
2014-09-11 Version 2.0 (Triumphant Giraffe) View change log
2013-08-26 Version 1.0 (unnamed)
2013-06-14 Version 0.9 (unnamed)