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-2017 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 a description property on a Manifest is a description of the object, whereas a description property on a Canvas is a description of that particular view.

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 the resource. This 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 pages or between 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, given as pairs of human readable label and value to be displayed to the user. There are no semantics conveyed by this information, only strings to present to the user. A pair might be used to convey to the user information such as information about the creation of the object, a physical description, or ownership information, amongst 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)"]}} ]}
description

A short textual description or summary of the resource that the property is attached to, intended to be conveyed to the user when the metadata fields are not being displayed.

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

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

A small content resource that represents the resource that the property is attached to, 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 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 the 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 the resource it is associated with is displayed or used. For example, this 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 the resource may be used. The rationale for this being a URI and not a human readable label is that typically there is one license for many resources, and the text is too long to be displayed to the user along with the object. If displaying the text 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 image that represents an individual or organization associated with the resource it is attached to. 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 the resource. It is recommended that an HTTPS URI be used for all resources.

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 of the resource. For the resource types defined by this specification, the value of type will be described in the sections below. For content resources, the type are drawn from other vocabularies. Recommendations for basic types such as image, text or audio are also given in the sections 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) of a content resource, for example “image/jpeg”. This is important for distinguishing text in XML from plain text, for example.

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"}
profile

A schema or named set of functionality available from the resource. The profile can further clarify the type and/or format of an external resource or service, allowing clients to customize their handling of the 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"
}

Specification Management Warning: Should there really be a table in the specification? But otherwise how do we keep it up to date between versions? If it’s external, how do clients stay up to date? URIs are always okay… should it instead always be a URI?

height

The height of a Canvas or 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 a Canvas or 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 a Canvas or 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}
renderingDirection

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 renderingDirection, and if so, it applies to the order in which its members are rendered.
    Clients should process renderingDirection on a Collection.
  • A Manifest may have exactly one renderingDirection, and if so, it applies to all of its sequences unless the sequence specifies its own value.
    Clients should process renderingDirection on a Manifest.
  • A Sequence may have exactly one renderingDirection.
    Clients should process renderingDirection on a Sequence.
  • A Range may have exactly one renderingDirection.
    Clients may process renderingDirection on a Range.
  • Other resource types must not have a renderingDirection.
    Clients should ignore renderingDirection 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.
{"renderingDirection": "left-to-right"}
renderingHint

A hint to the client as to the most appropriate method of displaying the resource. 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 an array of strings, taken from the table below or a full URI.

  • Any resource type may have one or more renderingHints.
    Clients should process renderingHint 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 hint, 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 renderingHint if none are specified.
paged Valid on Manifest, Sequence and Range. Canvases with this hint 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 hint.
continuous Valid on Manifest, Sequence and Range. A Canvas with this hint 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 hint has no implication for audio resources. The renderingDirection of the Sequence or Manifest will determine the appropriate arrangement of the Canvases.
multi-part Valid only for Collection. Collections with this hint 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 hint must not be presented in a page turning interface, and must be skipped over when determining the page sequence. This hint must be ignored if the current Sequence or Manifest does not have the ‘paged’ renderingHint.
facing-pages Valid only for Canvas. Canvases with this hint, in a Sequence or Manifest with the “paged” renderingHint, 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 hint 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 hint 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 hint, it should immediately proceed to the next Canvas and render it. If there is no subsequent Canvas in the current context, then this hint 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.
{"renderingHint": ["auto-advance", "individuals"]}
choiceHint

A hint associated with a Choice resource that a client can use to determine the publisher’s intent as to which agent should make the choice between the different options. In the absence of any choiceHint value, the rendering application can use any algorithm or process to make the determination. This specification defines the two 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.

  • A Choice may have exactly one choiceHint.
    Clients should process choiceHint on a Choice.
Value Description
client The client software is expected to select an appropriate option without user interaction.
user The client software is expected to present an interface to allow the user to explicitly select an option.
{"choiceHint": "client"}
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 the IIIF 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": "Related Web Page",
  "format": "text/html"}]}
rendering

A link to an external resource that is an alternative, non-IIIF representation of the IIIF resource. The external resource must be able to be displayed directly to a human user. 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": "PDF Rendering of Book",
  "format": "application/pdf"}]}
service

A link to an external service that the client might interact with directly, 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 a machine readable document that is related to the resource with the seeAlso property, such as an XML or RDF description. Properties of the document 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 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": "http://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 the current resource, such as a Manifest within a Collection.

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 a 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 a Range to an AnnotationCollection that includes the Annotations of content resources for that 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 a resource with pages, 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 a resource with pages 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 a paged list, 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 a 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 a 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 the current page, 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. 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.
{"structures": [
  {
    "id": "http://example.org/iiif/range/1",
    "type": "Range",
    "items": [{ ... }]
  }
]}
annotations

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

  • Any resource type Canvas should have a list of one or more AnnotationPages in content.
    Clients must process content on a Canvas.
{"annotations": [
  {
    "id": "http://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, described more simply as “http(s)”.

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.

{
  "thumbnail": [
    {"id": "http://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": "http://example.org/images/thumb1.jpg", "type": "Image"},
    {"id": "http://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, description, 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.

{"description": {
    "en": ["Here is the description of the object in English",
           "And a second description"],
    "fr": ["Voici la description de l'objet en français"],
    "@none": ["A description in an unknown language"]
  }
}

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 description, 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.

{"description": {"en-latn": ["<p>Short summary <b>description</b></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.

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": "http://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>"]}}
  ],
  "description": {"en": ["Book 1, written be Anne Author, published in Paris around 1400."]},

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

  // Presentation Information
  "renderingDirection": "right-to-left",
  "renderingHint": ["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": "http://example.org/logos/institution1.jpg",
    "service": {
        "id": "http://example.org/service/inst1",
        "type": "ImageService3",
        "profile": "level2"
    }
  },

  // Links
  "related": [{
    "id": "http://example.org/videos/video-book1.mpg",
    "type": "Video",
    "label": {"en":["Video discussing this book"]},
    "format": "video/mpeg"
  }],
  "service": [{
    "id": "http://example.org/service/example",
    "type": "Service",
    "profile": "http://example.org/docs/example-service.html"
  }],
  "seeAlso": [{
    "id": "http://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. All external Sequences must have an http(s) URI, and the description of the Sequence must be available by dereferencing that URI.

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"]},

  "renderingDirection": "left-to-right",
  "renderingHint": ["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.

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.

Renderers must scale content into the space represented by the Canvas, and should follow any timeMode adjustment 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.

Content resources are associated with the Canvas via Web Annotations. The Annotations are recorded in the items of one or more AnnotationPages, refered to in the content array of the Canvas. If the Annotation should be rendered quickly, in the view of the publisher, 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.

{
  // 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": [
        // 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 resource via id, type, and optionally label. 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/list/p1",
  "type": "AnnotationPage",

  "items": [
    {
      "id": "http://example.org/iiif/book1/list/p1/a1",
      "type": "Annotation"
      // ...
    },
    {
      "id": "http://example.org/iiif/book1/list/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, description, 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 describe additional structure within an object, such as newspaper articles that span pages or chapters within a book. Ranges can include Canvases, parts of Canvases, or other Ranges, creating a nested tree structure such as 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” renderingHint 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. Ranges are embedded or referenced within the Manifest in a structures property. Ranges then embed or reference other Ranges, Canvases or parts of Canvases in the items field. Each entry in the items field must be a JSON object, and it must have the id and type properties.

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

The Canvases and parts of Canvases may or may not be contiguous or in the same order as any Sequence. Examples include newspaper articles that are continued in different sections, or simply a chapter that starts half way through a page. Parts of Canvases must be rectangular and are described using the xywh= fragment approach.

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 provide the content resources.

{
  "@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": "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": "Introduction",
          "includes": "http://example.org/iiif/book1/layer/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/list/l1",
  "type": "AnnotationPage",
  "within": {
    "id": "http://example.org/iiif/book1/annocolls/transcription",
    "type": "AnnotationCollection",
    "label": "Diplomatic Transcription"
  }
}

// …

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://iiif.io/api/presentation/3/context.json"
  ],
  "id": "http://example.org/iiif/book1/layer/transcription",
  "type": "Layer",
  "label": "Diplomatic Transcription",
  // Other properties here ...

  "otherContent": [
    "http://example.org/iiif/book1/list/l1",
    "http://example.org/iiif/book1/list/l2",
    "http://example.org/iiif/book1/list/l3",
    "http://example.org/iiif/book1/list/l4"
    // More AnnotationLists here ...
  ]
}

5.8. Collection

Collections are used to list the manifests available for viewing, and to describe the structures, hierarchies or curated collections that the physical objects are part of. The collections may include both other collections and manifests, in order to form a hierarchy of objects with manifests at the leaf nodes of the tree. 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.

It is recommended that the topmost collection from which all other collections are discoverable by following links within the hierarchy be named top, if there is one.

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.

As such, collections must have a label, and should have metadata and description properties to be displayed by the client such that the user can understand the structure they are interacting with. If a collection does not have these properties, then a client is not required to render the collection to the user directly.

Collections have three list-based properties to express membership:

items

In cases where the order of a collection is significant, members can be used to interleave both collection and manifest resources. This is especially useful when a collection of books contains single- and multi-volume works (i.e. collections with the “multi-part” renderingHint), and when modeling archival material where original order is significant. Each entry in the members list must be an object and must include id, type, and label. If the entry is a collection, then renderingHint must also be present.

At least one of collections, manifests and members should be present in the response. 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": "Top Level Collection for Example Organization",
  "renderingHint": "top",
  "description": "Description of Collection",
  "attribution": "Provided by Example Organization",

  "collections": [
    {
      "id": "http://example.org/iiif/collection/sub1",
      "type": "Collection",
      "label": "Sub-Collection 1",

      "members": [  
        {
          "id": "http://example.org/iiif/collection/part1",
          "type": "Collection",
          "label": "My Multi-volume Set",
          "renderingHint": "multi-part"
        },
        {
          "id": "http://example.org/iiif/book1/manifest1",
          "type": "Manifest",
          "label": "My Book"
        },
        {
          "id": "http://example.org/iiif/collection/part2",
          "type": "Collection",
          "label": "My Sub Collection",
          "renderingHint": "individuals"
        }
      ]
    },
    {
      "id": "http://example.org/iiif/collection/part2",
      "type": "Collection",
      "label": "Sub Collection 2"
    }
  ],

  "manifests": [
    {
      "id": "http://example.org/iiif/book1/manifest",
      "type": "Manifest",
      "label": "Book 1"
    }
  ]
}

5.9. Paging

In some situations, annotation lists 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 corresponding list property (collections for a collection, otherContent for a layer). For example, a paged layer would link only to an annotation list as its first page. If known, the resource may also link to the last page.

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 layer, 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 Layer

A layer 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/layer/transcription",
  "type": "Layer",
  "label": "Example Long Transcription",

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

And the corresponding first annotation list:

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

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

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

Note that it is still expected that canvases will link directly to the annotation lists. For example, a particular canvas might refer to the first two annotation lists within a layer:

{
  "@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": "Page 1",

  "otherContent": [
    "http://example.org/iiif/book1/list/l1",
    "http://example.org/iiif/book1/list/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": "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. Requests

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

In the situation where the JSON documents are maintained in a filesystem with no access to the web server’s configuration, then including “.json” on the end of the URI is suggested to ensure that the correct content-type response header is sent to the client.

6.2. Responses

The format for all responses is JSON, and the following sections describe the structure to be returned.

The content-type of the response must be either application/json (regular JSON),

Content-Type: application/json

or “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 the client explicitly wants the JSON-LD content-type, then it must specify this in an Accept header, otherwise the server must return the regular JSON content-type.

The HTTP server should, if at all possible, send the Cross Origin Access Control header (often called “CORS”) to allow clients to download the manifests via AJAX from remote sites. The header name is Access-Control-Allow-Origin and the value of the header 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 and the conditional Content-type header 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 URL of the service, and clients are expected to look up the details from the full description by matching the URL. 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 description 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
AnnotationList optional optional optional optional optional optional optional
Range required optional optional optional optional optional optional
Layer 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 renderingDirection renderingHint 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
AnnotationList 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
Layer 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
AnnotationList optional optional optional optional optional not allowed
Range optional optional optional optional optional optional
Layer 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
AnnotationList not allowed not allowed not allowed optional optional optional
Range not allowed not allowed not allowed not allowed not allowed not allowed
Layer 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
AnnotationList 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
Layer 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 (first) optional
Sequence (second+) required
Canvas recommended
Annotation recommended
AnnotationList required
Range optional
Layer optional
Image Content required
Other Content required

B. Example Manifest Response

URL: http://example.org/iiif/book1/manifest

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

  "label": "Book 1",
  "metadata": [
    {"label": "Author", "value": "Anne Author"},
    {"label": "Published", "value": [
        {"@value": "Paris, circa 1400", "@language": "en"},
        {"@value": "Paris, environ 14eme siecle", "@language": "fr"}
        ]
    }
  ],
  "description": "A longer description of this example book. It should give some real information.",
  "navDate": "1856-01-01T00:00:00Z",

  "license": "http://example.org/license.html",
  "attribution": "Provided by Example Organization",
  "service": {
    "@context": "http://example.org/ns/jsonld/context.json",
    "id": "http://example.org/service/example",
    "profile": "http://example.org/docs/example-service.html"
  },
  "seeAlso":
    {
      "id": "http://example.org/library/catalog/book1.marc",
      "format": "application/marc",
      "profile": "http://example.org/profiles/marc21"
    },
  "rendering": {
    "id": "http://example.org/iiif/book1.pdf",
    "label": "Download as PDF",
    "format": "application/pdf"
  },
  "within": "http://example.org/collections/books/",

  "sequences": [
      {
        "id": "http://example.org/iiif/book1/sequence/normal",
        "type": "Sequence",
        "label": "Current Page Order",
        "renderingDirection": "left-to-right",
        "renderingHint": "paged",
        "canvases": [
          {
            "id": "http://example.org/iiif/book1/canvas/p1",
            "type": "Canvas",
            "label": "p. 1",
            "height":1000,
            "width":750,
            "images": [
              {
                "type": "Annotation",
                "motivation": "painting",
                "resource":{
                    "id": "http://example.org/iiif/book1/res/page1.jpg",
                    "type": "dctypes:Image",
                    "format": "image/jpeg",
                    "service": {
                        "@context": "http://iiif.io/api/image/2/context.json",
                        "id": "http://example.org/images/book1-page1",
                        "profile": "http://iiif.io/api/image/2/level1.json"
                    },
                    "height":2000,
                    "width":1500
                },
                "on": "http://example.org/iiif/book1/canvas/p1"
              }
            ],
            "otherContent": [
              {
                "id": "http://example.org/iiif/book1/list/p1",
                "type": "AnnotationList",
                "within": {
                    "id": "http://example.org/iiif/book1/layer/l1",
                    "type": "Layer",
                    "label": "Example Layer"
                }
              }
            ]
        },
          {
            "id": "http://example.org/iiif/book1/canvas/p2",
            "type": "Canvas",
            "label": "p. 2",
            "height":1000,
            "width":750,
            "images": [
              {
                "type": "Annotation",
                "motivation": "painting",
                "resource":{
                    "id": "http://example.org/images/book1-page2/full/1500,2000/0/default.jpg",
                    "type": "dctypes:Image",
                    "format": "image/jpeg",
                    "height":2000,
                    "width":1500,
                    "service": {
                        "@context": "http://iiif.io/api/image/2/context.json",
                        "id": "http://example.org/images/book1-page2",
                        "profile": "http://iiif.io/api/image/2/level1.json",
                        "height":8000,
                        "width":6000,
                        "tiles": [{"width": 512, "scaleFactors": [1,2,4,8,16]}]
                    }
                },
                "on": "http://example.org/iiif/book1/canvas/p2"
              }
            ],
            "otherContent": [
              {
                "id": "http://example.org/iiif/book1/list/p2",
                "type": "AnnotationList",
                "within": "http://example.org/iiif/book1/layer/l1"  
              }
            ]
          },
          {
            "id": "http://example.org/iiif/book1/canvas/p3",
            "type": "Canvas",
            "label": "p. 3",
            "height":1000,
            "width":750,
            "images": [
              {
                "type": "Annotation",
                "motivation": "painting",
                "resource":{
                    "id": "http://example.org/iiif/book1/res/page3.jpg",
                    "type": "dctypes:Image",
                    "format": "image/jpeg",
                    "service": {
                        "@context": "http://iiif.io/api/image/2/context.json",
                        "id": "http://example.org/images/book1-page3",
                        "profile": "http://iiif.io/api/image/2/level1.json"
          },
                    "height":2000,
                    "width":1500
                },
                "on": "http://example.org/iiif/book1/canvas/p3"
              }
            ],
            "otherContent": [
              {
                "id": "http://example.org/iiif/book1/list/p3",
                "type": "AnnotationList",
                "within": "http://example.org/iiif/book1/layer/l1"               
              }
            ]
          }
        ]
      }
    ],
  "structures": [
    {
      "id": "http://example.org/iiif/book1/range/r1",
        "type": "Range",
        "label": "Introduction",
        "canvases": [
          "http://example.org/iiif/book1/canvas/p1",
          "http://example.org/iiif/book1/canvas/p2",
          "http://example.org/iiif/book1/canvas/p3#xywh=0,0,750,300"
        ]
    }
  ]
}

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

The production of this document was generously supported by a grant from the Andrew W. Mellon Foundation.

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)