Presentation API 2.1.1

Status of this Document

This Version: 2.1.1

Latest Stable Version: 3.0.0

Previous Version: 2.0

Editors:

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


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 museum objects, books, newspapers, letters, manuscripts, maps, scrolls, single sheet collections, and digital surrogates of textiles, realia and ephemera. 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 the pages, surfaces or views of the object.
  • The display of text, and resources of other media types, associated with the object or its pages – 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 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 in which individual surfaces or views are presented (the sequence resource), and the individual surfaces or 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) or there may be groups of content resource above the page level, such as all of the texts that make up a single edition of a book (a layer resource). 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
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 canvas and images, text and other resources are “painted” on to it.

Content

Content resources such as images or texts that are associated with a canvas.

2.2. Additional Types

All Resource Types
All Resource Types
Collection

An ordered list of manifests, and/or further collections. Collections allow easy advertising and browsing of the manifests in a hierarchical structure, potentially with its own descriptive information. They can also provide clients with a means to locate all of the manifests known to the publishing institution.

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.

AnnotationList

An ordered list of annotations, typically associated with a single canvas.

Layer

An ordered list of annotation lists. Layers 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 page or view of the object.

The requirements for the use of the properties are summarized in Appendix B.

Other properties are allowed, either via custom extensions or endorsed by the 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. Services should be used for extensions if at all possible, and a JSON-LD context document should be added that defines the semantics of the new properties.

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.

  • A collection must have at least one label.
  • A manifest must have at least one label, such as the name of the object or title of the intellectual work that it embodies.
  • 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.
  • A canvas must have at least one label, such as the page number or short description of the view.
  • 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.
  • A range must have at least one label.
  • A layer must have at least one label.
  • Other resource types may have labels.
metadata

A list of short descriptive entries, given as pairs of human readable label and value to be displayed to the user. The value should be either simple HTML, including links and text markup, or plain text, and the label should be plain text. There are no semantics conveyed by this information, and clients should not use it for discovery or other purposes. This list of descriptive pairs should be able to be displayed in a tabular form in the user interface. Clients should have a way to display the information about manifests and canvases, and may have a way to view the information about other resources. The client should display the pairs in the order provided by the description. A pair might be used to convey the author of the work, information about its creation, a brief physical description, or ownership information, amongst other use cases. The client is not expected to take any action on this information beyond displaying the label and value. An example pair of label and value might be a label of “Author” and a value of “Jehan Froissart”.

  • A collection should have one or more metadata pairs associated with it.
  • A manifest should have one or more metadata pairs associated with it describing the object or work.
  • Other resource types may have one or more metadata pairs.
description

A longer-form prose description of the object or resource that the property is attached to, intended to be conveyed to the user as a full text description, rather than a simple label and value. It may be in simple HTML or plain text. It can duplicate any of the information from the metadata fields, along with additional information required to understand what is being displayed. Clients should have a way to display the descriptions of manifests and canvases, and may have a way to view the information about other resources.

  • A collection should have one or more descriptions.
  • A manifest should have one or more descriptions.
  • Other resource types may have one or more description.
thumbnail

A small image that depicts or pictorially represents the resource that the property is attached to, such as the title page, a significant image or rendering of a canvas with multiple content resources associated with it. It is recommended that a IIIF Image API service be available for this image for manipulations such as resizing. If a resource has multiple thumbnails, then each of them should be different.

  • A collection should have exactly one thumbnail image, and may have more than one.
  • A manifest should have exactly one thumbnail image, and may have more than one.
  • A sequence may have one or more thumbnails and should have at least one thumbnail if there are multiple sequences in a single manifest.
  • A canvas may have one or more thumbnails and should have at least one thumbnail if there are multiple images or resources that make up the representation.
  • 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.
  • Other resource types may have one or more thumbnails.

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, and a client must make these properties clearly available to the user. 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 bars.

attribution

Text that must be shown 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. Clients should try to match the language preferred by the user, and if the preferred language is unknown or unavailable, then the client may choose which value to display. If there are multiple values of the same or unspecified language, then all of those values must be displayed.

  • Any resource type may have one or more attribution labels.
license

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.

  • Any resource type may have one or more licenses associated with it.

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 manipulations such as resizing.

  • Any resource type may have one or more logos associated with it.

3.3. Technical Properties

@id

The URI that identifies the resource. It is recommended that an HTTP URI be used for all resources. Recommended HTTP URI patterns for the different classes of resource are given below. URIs from any registered scheme may be used, and implementers may find it convenient to use a UUID URN of the form: "urn:uuid:uuid-goes-here-1234". Resources that do not require URIs may be assigned blank node identifiers; this is the same as omitting @id.

  • A collection must have exactly one id, and it must be the http(s) URI at which it is published.
  • A manifest must have exactly one id, and it must be the http(s) URI at which it is published.
  • A sequence may have an id and must not have more than one.
  • A canvas must have exactly one id, and it must be an http(s) URI. The canvas’s JSON representation should be published at that URI.
  • A content resource must have exactly one id unless it is embedded in the response, and it must be the http(s) URI at which the resource is published.
  • A range must have exactly one id, and it must be an http(s) URI.
  • A layer must have exactly one id, and it must be an http(s) URI.
  • An annotation list must have exactly one id, and it must be the http(s) URI at which it is published.
  • An annotation should have exactly one id, must not have more than one, and the annotation’s representation should be published at that URI.
@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 may be drawn from other vocabularies. Recommendations for basic types such as image, text or audio are also given in the sections below.

  • All resource types must have at least one type specified.

This requirement applies only to the types described in Section 2. Services, Thumbnails and other resources will have their own requirements.

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.

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

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.

height

The height of a canvas or image resource. For images, 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.

  • A canvas must have exactly one height.
  • Content resources may have exactly one height, given in pixels, if appropriate.
  • Other resource types must not have a height.
width

The width of a canvas or image resource. For images, 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.

  • A canvas must have exactly one width.
  • Content resources may have exactly one width, given in pixels, if appropriate.
  • Other resource types must not have a width.
viewingDirection

The direction that a sequence of canvases should be displayed to the user. Possible values are specified in the table below.

  • A manifest may have exactly one viewing direction, and if so, it applies to all of its sequences unless the sequence specifies its own viewing direction.
  • A sequence may have exactly one viewing direction.
  • A range or layer may have exactly one viewing direction.
  • Other resource types must not have a viewing direction.
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.
viewingHint

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. Other values may be given, and if they are, they must be URIs.

  • Any resource type may have one or more viewing hints.
Value Description
individuals Valid on collection, manifest, sequence and range. When used as the viewingHint of a collection, the client should treat each of the manifests as distinct individual objects. For manifest, sequence and range, the canvases referenced are all distinct individual views, and should not be presented in a page-turning interface. Examples include a gallery of paintings, a set of views of a 3 dimensional object, or a set of the front sides of photographs in a collection.
paged Valid on manifest, sequence and range. Canvases with this viewingHint 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 represents the back of the object in the first canvas.
continuous Valid on manifest, sequence and range. A canvas with this viewingHint is a partial view and an appropriate rendering might display either the canvases individually, or all of the canvases virtually stitched together in the display. Examples when this would be appropriate include long scrolls, rolls, or objects designed to be displayed adjacent to each other. If this viewingHint is present, then the resource must also have a viewingDirection which will determine the arrangement of the canvases. Note that this does not allow for both sides of a scroll to be included in the same manifest with this viewingHint. To accomplish that, the manifest should be “individuals” and have two ranges, one for each side, which are “continuous”.
multi-part Valid only for collections. Collections with this viewingHint consist of multiple manifests that each form part of a logical whole. Clients might render the collection as a table of contents, rather than with thumbnails. Examples include multi-volume books or a set of journal issues or other serials.
non-paged Valid only for canvases. Canvases with this viewingHint must not be presented in a page turning interface, and must be skipped over when determining the page sequence. This viewing hint must be ignored if the current sequence or manifest does not have the ‘paged’ viewing hint.
top Valid only for ranges. A Range with this viewingHint is the top-most node in a hierarchy of ranges that represents a structure to be rendered by the client to assist in navigation. For example, a table of contents within a paged object, major sections of a 3d object, the textual areas within a single scroll, and so forth. Other ranges that are descendants of the “top” range are the entries to be rendered in the navigation structure. There may be multiple ranges marked with this hint. If so, the client should display a choice of multiple structures to navigate through.
facing-pages Valid only for canvases. Canvases with this viewingHint, in a sequence or manifest with the “paged” viewing hint, 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.

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.
  • Other resource types must not have navigation dates.

3.4. Linking Properties

A link to an external resource intended to be displayed directly to the user, and is related to the resource that has the related property. Examples might include a video or academic paper about the resource, a website, an HTML description, and so forth. A label and the format of the related resource should be given to assist clients in rendering the resource to the user.

  • Any resource type may have one or more external resources related to it.
rendering

A link to an external resource intended for display or download by a human user. This property can be used to link from a manifest, collection or other resource to the preferred viewing environment for that 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. A label and the format of the rendering resource must be supplied to allow clients to present the option to the user.

  • Any resource type may have one or more external rendering resources.
service

A link to a service that makes more functionality available for the resource, such as from an image to the base URI of an associated IIIF Image API service. The service resource should have additional information associated with it in order to allow the client to determine how to make appropriate use of it, such as a profile link to a service description. It may also have relevant information copied from the service itself. This duplication is permitted in order to increase the performance of rendering the object without necessitating additional HTTP requests. Please see the Service Profiles document for known services.

  • Any resource type may have one or more links to an external service.
seeAlso

A link to a machine readable document that semantically describes the resource with the seeAlso property, such as an XML or RDF description. This document could be used for search and discovery or inferencing purposes, or just to provide a longer description of the resource. The profile and format properties of the document should be given to help the client to make appropriate use of the document.

  • Any resource type may have one or more external descriptions related to it.
within

A link to a resource that contains the current resource, such as annotation lists within a layer. This also allows linking upwards to collections that allow browsing of the digitized objects available.

  • Collections or annotation lists that serve as pages must be within exactly one paged resource.
  • Other resource types, including collections or annotation lists not serving as pages, may be within one or more containing resources.
startCanvas

A link from a sequence or range to a canvas that is contained within the sequence. 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.

  • A sequence or a range may have exactly one canvas as its start canvas.
  • Other resource types must not have a start canvas.
contentLayer

A link from a range to a layer 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.

  • A range may have exactly one layer as its content layer.
  • Other resource types must not have a content layer.

3.5. Paging Properties

first

A link from a resource with pages, such as a collection or layer, to its first page resource, another collection or an annotation list respectively. The page resource should be referenced by just its URI (from @id) but may also have more information associated with it as an object.

  • A collection may have exactly one collection as its first page.
  • A layer may have exactly one annotation list as its first page.
  • Other resource types must not have a first page.
last

A link from a resource with pages to its last page resource. The page resource should be referenced by just its URI (from @id) but may also have more information associated with it as an object.

  • A collection may have exactly one collection as its last page.
  • A layer may have exactly one annotation list as its last page.
  • Other resource types must not have a last page.
total

The total number of leaf resources, such as annotations within a layer, within a list of pages. 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.
  • A layer may have exactly one total, which must be the total number of annotations in its list of pages.
  • Other resource types must not have a total.
next

A link from a page resource to the next page resource that follows it in order. The resource should be referenced by just its URI (from @id) but may also have more information associated with it as an object.

  • A collection may have exactly one collection as its next page.
  • An annotation list may have exactly one annotation list as its next page.
  • Other resource types must not have next pages.
prev

A link from a page resource to the previous page resource that precedes it in order. The resource should be referenced by just its URI (from @id) but may also have more information associated with it as an object.

  • A collection may have exactly one collection as its previous page.
  • An annotation list may have exactly one annotation list as its previous page.
  • Other resource types must not have previous pages.
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 paging collection.
  • An annotation list may have exactly one startIndex, which must be the index of its first annotation relative to the order established by its paging layer.
  • Other resource types must not have a startIndex.

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.

4.1. 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 may be either given as just the URI if there is no additional information associated with them, or as a JSON object with the @id property. Other URI schemes may be used if the resource is not able to be retrieved via HTTP. Both options provide the same URI, however the second pattern associates additional information with the resource:

// Option A, plain string
{"seeAlso": "http://example.org/descriptions/book1.xml"}
// Option B, object with @id property
{"seeAlso": {"@id": "http://example.org/descriptions/book1.xml", "format": "text/xml"}}

4.2. Repeated Properties

Many of the properties in the API may be repeated. This is done by giving a list of values, using either of the representations described above, rather than a single string.

{
  "seeAlso": [
    "http://example.org/descriptions/book1.md",
    "http://example.org/descriptions/book1.csv",
    {"@id": "http://example.org/descriptions/book1.xml", "format": "text/xml"}
  ]
}

4.3. Language of Property Values

Language may be associated with strings that are intended to be displayed to the user with the following pattern of @value plus the RFC 5646 code in @language, instead of a plain string. For example:

{"description": {"@value": "Here is a longer description of the object", "@language": "en"}}

This pattern may be used in label, description, attribution and the label and value fields of the metadata construction.

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 none of the values have a language associated with them, the client must display all of the 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.

4.4. HTML Markup in Property Values

Minimal HTML markup may be included in the description, attribution and metadata properties. 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 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, and span tags. Clients may choose to remove any and all tags, therefore it should not be assumed that the formatting will always be rendered.

{"description": {"@value": "<p>Some <b>description</b></p>", "@language": "en-latn"}}

4.5. 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 within a manifest, the sequence must not have the @context field.

{"@context": "http://iiif.io/api/presentation/2/context.json"}

Any additional fields beyond those defined in this specification should be mapped to RDF predicates using further context documents. In this case, the enclosing object must have its own @context property, and it should be the first key/value pair of that object. This is required for service links that embed any information beyond a profile. These contexts should not redefine profile. As the top level resource must have the IIIF Presentation API context, if there are any additional contexts needed, the value will become an array of URI strings:

{
  "@context": [
    "http://iiif.io/api/presentation/2/context.json",
    "http://example.org/extension/context.json"
  ]
}

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 B provides summary tables of the property requirements.

5.1. Manifest

Recommended URI pattern:

{scheme}://{host}/{prefix}/{identifier}/manifest

The manifest response contains sufficient information for the client to initialize itself and begin to display something quickly to the user. The manifest resource 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 identifier in @id must always 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 a sequences 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. The first such sequence must be included within the manifest as well as optionally being available from its own URI. Subsequent sequences must only be referenced with their identifier (@id), class (@type) and label and thus must be dereferenced by clients in order to process them if the user selects to view that sequence.

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.

The example below includes only the manifest-level information, however actual implementations must embed the first sequence, canvas and content information. It includes examples in the descriptive metadata of how to associate multiple entries with a single field and how to be explicit about the language of a particular entry.

{
  // Metadata about this manifest file
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/manifest",
  "@type": "sc:Manifest",

  // Descriptive metadata about the object/work
  "label": "Book 1",
  "metadata": [
    {"label": "Author", "value": "Anne Author"},
    {"label": "Published", "value": [
        {"@value": "Paris, circa 1400", "@language": "en"},
        {"@value": "Paris, environ 1400", "@language": "fr"}
      ]
    },
    {"label": "Notes", "value": ["Text of note 1", "Text of note 2"]},
    {"label": "Source",
     "value": "<span>From: <a href=\"http://example.org/db/1.html\">Some Collection</a></span>"}
  ],
  "description": "A longer description of this example book. It should give some real information.",
  "thumbnail": {
    "@id": "http://example.org/images/book1-page1/full/80,100/0/default.jpg",
    "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"
    }
  },

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

  // Rights Information
  "license": "http://rightsstatements.org/vocab/NoC-NC/1.0/",
  "attribution": "Provided by Example Organization",

  "logo": {
    "@id": "http://example.org/logos/institution1.jpg",
    "service": {
        "@context": "http://iiif.io/api/image/2/context.json",
        "@id": "http://example.org/service/inst1",
        "profile": "http://iiif.io/api/image/2/level2.json"
    }
  },

  // Links
  "related":{
    "@id": "http://example.org/videos/video-book1.mpg",
    "format": "video/mpeg"
  },
  "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.xml",
    "format": "text/xml",
    "profile": "http://example.org/profiles/bibliographic"
  },
  "rendering": {
    "@id": "http://example.org/iiif/book1.pdf",
    "label": "Download as PDF",
    "format": "application/pdf"
  },
  "within": "http://example.org/collections/books/",

  // List of sequences
  "sequences": [
      {
        "@id": "http://example.org/iiif/book1/sequence/normal",
        "@type": "sc:Sequence",
        "label": "Current Page Order"
        // sequence's page order should be included here, see below...
      }
      // Any additional sequences can be referenced here...
  ]
}

5.2. Sequence

Recommended URI pattern:

{scheme}://{host}/{prefix}/{identifier}/sequence/{name}

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, and may also be available from its own URI. The default sequence may have a URI to identify it. Any additional sequences must be referred to from the manifest, not embedded within it, and thus these additional sequences must have an HTTP URI.

The {name} parameter in the URI structure must distinguish it from any other sequences that may be available for the physical object. Typical default names for sequences are “normal” or “basic”.

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 pages in the object, represented by canvas resources, are listed in order in the canvases property. There must be at least one canvas given.

Sequences may have a startCanvas with a single value containing the URI of a canvas resource that is contained within the sequence. This is the canvas that a viewer should initialize its display with for the user. If it is not present, then the viewer should use the first canvas in the sequence.

In the manifest example above, the sequence is referenced by its URI and contains only the basic information of label, @type and @id. The default sequence should be written out in full within the manifest file, as below but must not have the @context property.

{
  // Metadata about this sequence
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/sequence/normal",
  "@type": "sc:Sequence",
  "label": "Current Page Order",

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

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

5.3. Canvas

Recommended URI pattern:

{scheme}://{host}/{prefix}/{identifier}/canvas/{name}

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. If following the recommended URI pattern, the {name} parameter must uniquely distinguish the canvas from all other canvases in the object. The URI of the canvas should 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.

Every canvas must have a label to display, and a height and a width as integers. A canvas is a two-dimensional rectangular space with an aspect ratio that represents a single logical view of some part of the object, and the aspect ratio is given with the height and width properties. This allows resources to be associated with specific parts of the canvas, rather than the entire space. Content must not be associated with space outside of the canvas’s dimensions, such as at coordinates below 0,0 or greater than the height or width.

It is recommended that if there is (at the time of implementation) a single image that depicts the page, then the dimensions of the image are used as the dimensions of the canvas for simplicity. If there are multiple full images, then the dimensions of the largest image should be used. If the largest image’s dimensions are less than 1200 pixels on either edge, then the canvas’s dimensions should be double those of the image. Clients must be aware that this is not always the case, such as in the examples presented, and instead must always scale images into the space represented by the canvas. The dimensions of the canvas should be the same scale as the physical object, and thus images should depict only the object. This can be accomplished by cropping the image, or associating only a segment of the image with the canvas. The physical dimensions of the object may be available via a service, either embedded within the description or requiring an HTTP request to retrieve them.

Image resources, and only image resources, are included in the images property of the canvas. These are linked to the canvas via annotations, as described in Image Resources. Other content, such as transcriptions, video, audio or commentary, is provided via external annotation lists referenced in the otherContent property, as described in Annotation Lists. The value of both of these properties must be a list, even if there is only one entry. Both are optional, as there may be no additional information associated with the canvas. Note that the items in the otherContent list may be either objects with an @id property or strings. In the case of a string, this is the URI of the annotation list and the type of “sc:AnnotationList” can be inferred.

In a sequence with the viewingHint value of “paged” and presented in a book viewing user interface, the first canvas should be presented by itself – it is typically either the cover or first recto page. Thereafter, the canvases represent the sides of the leaves, and hence may be presented with two canvases displayed as an opening of the book. If there are canvases which are in the sequence but would break this ordering, then they must have the viewingHint property with a value of “non-paged”. Similarly if the first canvas is not a single up, it must be marked as “non-paged” or an empty canvas added before it.

Canvases may be dereferenced separately from the manifest via their URIs, and the following representation information should be returned. This information should be embedded within the sequence, as per previously.

{
  // Metadata about this canvas
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/canvas/p1",
  "@type": "sc:Canvas",
  "label": "p. 1",
  "height": 1000,
  "width": 750,
  "thumbnail" : {
    "@id" : "http://example.org/iiif/book1/canvas/p1/thumb.jpg",
    "@type": "dctypes:Image",
    "height": 200,
    "width": 150
  },
  "images": [
    {
      "@type": "oa:Annotation"
      // Link from Image to canvas should be included here, as below
    }
  ],
  "otherContent": [
    {
      // Reference to list of other Content resources, _not included directly_
      "@id": "http://example.org/iiif/book1/list/p1",
      "@type": "sc:AnnotationList"
    }
  ]

}

5.4. Image Resources

Recommended URI pattern:

{scheme}://{host}/{prefix}/{identifier}/annotation/{name}

Association of images with their respective canvases is done via annotations. Although normally annotations are used for associating commentary with the thing the annotation’s text is about, the Open 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.

Annotations may have their own URIs, conveyed by adding an @id property to the JSON object, and if so should be HTTP URIs. The content of the annotation should be returned if the URI is dereferenced. Annotations may be dereferenced separately from their annotation lists, sequences and manifests; some systems may do this and identifiers should be given using the recommended pattern if possible.

Each association of an image must have the motivation field and the value must be “sc:painting”. This is in order to distinguish it from comment annotations about the canvas, described in further detail below. Note that all resources which are to be displayed as part of the representation are given the motivation of “sc:painting”, regardless of whether they are images or not. For example, a transcription of the text in a page is considered “painting” as it is a representation of the object, whereas a comment about the page is not.

The image itself is linked in the resource property of the annotation. The image must have an @id field, with the value being the URI at which the image can be obtained. If a IIIF Image service is available for the image, then the URL may be the complete URL to a particular size of the image content, such as http://example.org/image1/full/1000,/0/default.jpg. It should have an @type of “dctypes: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.

If a IIIF Image API service is available for the image, then a link to the service’s base URI should be included. The base URI is the URI up to the identifier, but not including the trailing slash character or any of the subsequent parameters. A reference to the Image API context document must be included and the conformance level profile of the service should be included. Additional fields from the Image Information document may be included in this JSON object to avoid requiring it to be downloaded separately. See the annex on using external services for more information.

Although it seems redundant, the URI of the canvas must be repeated in the on field of the Annotation. This is to ensure consistency with annotations that target only part of the resource, described in more detail below.

Additional features of the Open 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. These additional features are described in the following section. The use of advanced features sometimes results in situations where the resource is not an image, 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 an image.

Only the annotations that associate images or parts of images are included in the canvas in the images property. Other annotations, including both those that paint resources on the canvas and those that comment about the canvas, are included by referencing annotation lists, discussed in the following section.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/p0001-image",
  "@type": "oa:Annotation",
  "motivation": "sc: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/level2.json"
    },
    "height":2000,
    "width":1500
  },
  "on": "http://example.org/iiif/book1/canvas/p1"
}

5.5. Annotation List

Recommended URI pattern:

{scheme}://{host}/{prefix}/{identifier}/list/{name}

For some objects, there may be more than just images available to represent the page. Other resources could include the full text of the object, musical notations, musical performances, diagram transcriptions, commentary annotations, tags, video, data and more. These additional resources are included in annotation lists, referenced from the canvas they are associated with.

Annotation Lists are separate resources that should be dereferenced when encountered. They are collections of annotations, where each annotation targets the Canvas or part thereof. The separation from the manifest representation is intended to allow clients to quickly display the images to the user, and then populate the display with further content and commentary when the user navigates to a particular canvas. It also allows the annotation list to be generated dynamically, while the manifest is static and more easily cached.

The {name} parameter in the URI pattern must uniquely distinguish it from all other lists, and is typically the same name as the canvas. As a single canvas may have multiple lists of additional resources, perhaps divided by type, this must not be assumed however, and the URIs must be followed rather than constructed a priori.

The annotation list 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.

The annotations, as described above, are given in a resources list. The resource linked by the annotation must be something other than an image if the motivation is sc:painting, these are recorded in the images property of the canvas. The canvas URI must be repeated in the on field, as above.

The format of the resource should be included and must be the media type that is returned when the resource is dereferenced. The type of the content resource should be taken from this list in the Open Annotation specification, or a similar well-known resource type ontology. For resources that are displayed as part of the rendering (such as images, text transcriptions, performances of music from the manuscript and so forth) the motivation must be “sc:painting”. The content resources may also have any of the other fields defined in this specification, including commonly label, description, metadata, license and attribution.

Note well that Annotation Lists must not be embedded within the manifest.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/list/p1",
  "@type": "sc:AnnotationList",

  "resources": [
    {
      "@type": "oa:Annotation",
      "motivation": "sc:painting",
      "resource":{
        "@id": "http://example.org/iiif/book1/res/music.mp3",
        "@type": "dctypes:Sound",
        "format": "audio/mpeg"
      },
      "on": "http://example.org/iiif/book1/canvas/p1"
    },
    {
      "@type": "oa:Annotation",
      "motivation": "sc:painting",
      "resource":{
        "@id": "http://example.org/iiif/book1/res/tei-text-p1.xml",
        "@type": "dctypes:Text",
        "format": "application/tei+xml"
      },
      "on": "http://example.org/iiif/book1/canvas/p1"
    }
    // ... and so on
  ]
}

5.6. Range

Recommended URI pattern:

{scheme}://{host}/{prefix}/{identifier}/range/{name}

It may be important to describe additional structure within an object, such as newspaper articles that span pages, the range of non-content-bearing pages at the beginning of a work, or chapters within a book. These are described using ranges in a similar manner to sequences. Ranges must have URIs and they should be http(s) URIs. The intent of adding a range to the manifest is to allow the client to display a structured hierarchy to enable the user to navigate within the object without merely stepping through the current sequence. The rationale for separating ranges from sequences is that there is likely to be overlap between different ranges, such as the physical structure of a book compared to the textual structure of the work. An example would be a newspaper with articles that are continued in different sections, or simply a section that starts half way through a page.

Ranges are linked or embedded within the manifest in a structures field. It is a flat list of objects, even if there is only one range.

Ranges have three list based properties to express membership:

ranges

References to ranges within the current range. Each included range must be referenced via a string containing the range’s URI.

canvases

References to canvases, or rectangular parts of a canvas, within the current range. Each included canvas must be referenced via a string containing the canvas’s URI.

members

A combined list of both ranges and canvases. If the range contains both other ranges and canvases, and the ordering of the different types of resource is significant, the range should instead use the members property. The property’s value is an array of canvases, parts of canvases or other ranges. Each item in the array must be an object, and it must have the @id, @type, and label properties.

A range will typically include one or more canvases or, unlike sequences, parts of canvases. The part must be rectangular, and is given using the xywh= fragment approach. This allows for selecting, for example, the areas within two newspaper pages where an article is located. An empty range, with no member resources, is allowed but discouraged. The reason for the empty range could be described in the label property, or in the description property for more discursive text.

In order to present a table of the different ranges to allow a user to select one, every range must have a label and the top most range in the table should have a viewingHint with the value “top”. A range that is the top of a hierarchy does not need to list all of the canvases in the sequence, and should only give the list of ranges below it. Ranges may also have any of the other properties defined in this specification, including the startCanvas relationship to the first canvas within the range to start with, if it is not the first listed in canvases or members.

Ranges may also link to a layer, described in the next section, that has the content of the range using the contentLayer linking property. The referenced layer will contain one or more annotation lists, each of which contains annotations that target the areas of canvases within the range, and provide the content resources. This allows, for example, the range representing a newspaper article that is split across multiple pages to be linked with the text of the article. Rendering clients might use this to display all of the article text, regardless of which canvas is being viewed.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/manifest",
  "@type": "sc:Manifest",
  // Metadata here ...

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

  "structures": [
    {
      "@id": "http://example.org/iiif/book1/range/r0",
      "@type": "sc:Range",
      "label": "Table of Contents",
      "viewingHint": "top",
      "members": [
        {
          "@id": "http://example.org/iiif/book1/canvas/cover",
          "@type": "sc:Canvas",
          "label": "Front Cover"
        },
        {
          "@id": "http://example.org/iiif/book1/range/r1",
          "@type": "sc:Range",
          "label": "Introduction",
          "contentLayer": "http://example.org/iiif/book1/layer/introTexts"
        },
        {
          "@id": "http://example.org/iiif/book1/canvas/backCover",
          "@type": "sc:Canvas",
          "label": "Back Cover"
        }
      ]
    },
    {
      "@id": "http://example.org/iiif/book1/range/r1",
      "@type": "sc:Range",
      "label": "Introduction",
      "ranges": ["http://example.org/iiif/book1/range/r1-1"],
      "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"
      ]
    },
    {
      "@id": "http://example.org/iiif/book1/range/r1-1",
      "@type": "sc:Range",
      "label": "Objectives and Scope",
      "canvases": ["http://example.org/iiif/book1/canvas/p2#xywh=0,0,500,500"]
    }
  ]
}

Deprecation Warning Several issues have arisen with respect to the current specification for ranges, and a new pattern is anticipated in API version 3.0 to address these concerns. Feedback on this deprecation is requested.

5.7. Layer

Recommended URI pattern:

{scheme}://{host}/{prefix}/{identifier}/layer/{name}

Layers represent groupings of annotation lists that should be collected together, regardless of which canvas they target, such as all of the annotations that make up a particular translation of the text of a book. Without the layer construction, it would be impossible to determine which annotations belonged together across canvases. A client might then present a user interface that allows all of the annotations in a layer to be displayed or hidden according to the user’s preference.

Layers 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.

Each annotation list may be part of one or more layers. If the annotation list is part of a layer, then this must be recorded using the within relationship in the annotation list response. It may also be included in the reference to the annotation list in the manifest response. In the manifest response, the description of the layer may be omitted after the first use, and just the URI given as a string. Clients should refer to the first description given, based on the URI.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/list/l1",
  "@type": "sc:AnnotationList",
  "within": {
    "@id": "http://example.org/iiif/book1/layer/transcription",
    "@type": "sc:Layer",
    "label": "Diplomatic Transcription"
  }
}

The layer may be able to be dereferenced if it has an HTTP URI. If a representation is available, it must follow all of the requirements for JSON representations in this specification. All of the properties of the layer should be included in the representation.

The annotation lists are referenced from the layer in an otherContent array, in the same way as they are referenced from a canvas. The annotation lists should be given as just URIs, but may be objects with more information about them, such as in the Canvas example.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/layer/transcription",
  "@type": "sc: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

Recommended URI pattern:

{scheme}://{host}/{prefix}/collection/{name}

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.

The URI pattern follows the same structure as the other resource types, however note that it prevents the existence of a manifest or object with the identifier “collection”. It is also recommended that the topmost collection from which all other collections are discoverable by following links within the heirarchy 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:

collections

References to sub-collections of the current collection. Each referenced collection must have the appropriate @id, @type and label, and may be embedded in its entirety.

manifests

References to manifests contained within the current collection. Each referenced manifest must have the appropriate @id, @type and label.

members

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” viewingHint), 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 viewingHint 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://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/collection/top",
  "@type": "sc:Collection",
  "label": "Top Level Collection for Example Organization",
  "viewingHint": "top",
  "description": "Description of Collection",
  "attribution": "Provided by Example Organization",

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

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

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

Deprecation Warning The collections and manifests properties are likely to be removed in version 3.0 in favor of the single members property. Until that time, if a client sees a members property, it should use that property even if collections and/or manifests are also present. However, publishing systems should be aware that Presentation API version 2.0-compliant clients will not produce the expected results if they use members and do not provide a fall back with collections and manifests. Publishing systems should only use members when it is important to have a single ordered list that contains both collections and manifests. Feedback on this deprecation is requested.

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://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/layer/transcription",
  "@type": "sc:Layer",
  "label": "Example Long Transcription",

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

And the corresponding first annotation list:

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/list/l1",
  "@type": "sc: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://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/canvas/c1",
  "@type": "sc: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://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/collection/top",
  "@type": "sc:Collection",
  "label": "Example Big Collection",

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

And the corresponding first page of manifests:

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/collection/c1",
  "@type": "sc:Collection",

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

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

6. Advanced Association Features

The following sections describe known use cases for building representations of objects using the IIIF Presentation API, and clients should expect to encounter them. Other use cases are likely to exist, and must be encoded using the Open Annotation’s context document mapping for any additional fields required.

6.1. Segments

It is important to be able to extract parts, or segments, of resources. In particular a very common requirement is to associate a resource with part of a canvas, or part of an image with either the entire canvas or part thereof. Secondly, as transcriptions are often made available in XML files, extracting the correct page to associate with the canvas, or line to associate with part of the canvas, is equally useful for reusing existing material. These can be accomplished using URI fragments for simple cases.

Note that if there are segments of both image and canvas, then the aspect ratio should be the same, but there are circumstances where they may be different. In this case the rendering agent should rescale the image segment to the dimensions provided on the canvas.

Segments of both static images and canvases may be selected by adding a rectangular bounding box after the URI. The fragment must take the form of #xywh= as per the example below where the four numbers are the x and y coordinates of the top left hand corner of the bounding box in the image or canvas, followed by the width and height. Thus the segment above is 300px wide, 50px high and starts at position 100,100. Note that only integers are allowed in this syntax, and this may limit accuracy of assignment to canvases with small dimensions.

http://www.example.com/iiif/book1/canvas/p1#xywh=100,100,300,50

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    // Crop out scanning bed
    "@id": "http://example.org/iiif/book1/res/page1.jpg#xywh=40,50,1200,1800",
    "@type": "dctypes:Image",
    "format": "image/jpeg"
  },
  // canvas size is 1200x1800
  "on": "http://example.org/iiif/book1/canvas/p1"
}

For image resources with a IIIF Image API service, it is recommended to instead use the Image API parameters rather than a fragment as above. The following structure allows simple clients to use the image directly (the URL with the segment), and allows clients that implement the IIIF Image API to have sufficient information to construct appropriate URIs using the API.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource": {
    "@id": "http://www.example.org/iiif/book1-page1/50,50,1250,1850/full/0/default.jpg",
    "@type": "oa:SpecificResource",
    "full": {
      "@id": "http://example.org/iiif/book1-page1/full/full/0/default.jpg",
      "@type": "dctypes:Image",
      "service": {
        "@context": "http://iiif.io/api/image/2/context.json",
        "@id": "http://example.org/iiif/book1-page1",
        "profile": "http://iiif.io/api/image/2/level2.json"
      }
    },
    "selector": {
      "@context": "http://iiif.io/api/annex/openannotation/context.json",
      "@type": "iiif:ImageApiSelector",
      "region": "50,50,1250,1850"
    }
  },
  "on": "http://www.example.org/iiif/book1/canvas/p1#xywh=0,0,600,900"      
}

Segments of XML files may be extracted with XPaths. The fragment must be structured as follows:

http://www.example.com/iiif/book1/res/tei.xml#xpointer(/xpath/to/element)

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@id": "http://example.org/iiif/book1/res/tei.xml#xpointer(//line[1])",
    "@type": "dctypes:Text",
    "format": "application/tei+xml"
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,100,500,300"
}

6.2. Embedded Content

Instead of referencing transcription text externally, it is often easier to record it within the annotation itself. Equally, text based comments could also benefit from being included in the annotation that associates the comment with the canvas.

Content may be embedded instead of referenced by using the following pattern within the annotation block:

{"resource": {"@type": "cnt:ContentAsText", "chars": "text here"}}

The media type should be provided using the format field, and while any media type is possible, it is recommended that text/plain or text/html be used to maximize compatibility.

If it is desirable to describe the language of the content, then it must be given with the language property not @language.

An example of this feature:

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/p1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@type": "cnt:ContentAsText",
    "chars": "Here starts book one...",
    "format": "text/plain",
    "language": "en"
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,150,500,25"
}

6.3. Choice of Alternative Resources

A common requirement is to have a choice between multiple images that depict the page, such as being photographed under different lights or at different times. This can be accomplished by having a “oa:Choice” object as the resource, which then refers to the options to select from. It must have one default and at least one further item to choose from. The images should have a label for the viewer to display to the user so they can make their selection from among the options.

The same construction can be applied to a choice between other types of resources as well. This is described in the Multiplicity section of the Open Annotation specification.

Either the default or item may have a value of “rdf:nil”. This means that a valid option is not to display anything. This must not have a label associated with it, viewers should either use “Nothing” or an appropriate label of their choice.

This can be used to model foldouts and other dynamic features of a page, by associating images of the different states with the canvas. Depending on the nature of the images, this can be done such that either the entire image is switched to change state, or only the section of the image that has to change is switched, if the appropriate segment information is known.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@type": "oa:Choice",
    "default":{
      "@id": "http://example.org/iiif/book1/res/page1.jpg",
      "@type": "dctypes:Image",
      "label": "Color"
    },
    "item": [
      {
        "@id": "http://example.org/iiif/book1/res/page1-blackandwhite.jpg",
        "@type": "dctypes:Image",
        "label": "Black and White"
      }
    ]
  },
  "on": "http://example.org/iiif/book1/canvas/p1"
}

6.4. Non Rectangular Segments

The Scalable Vector Graphics standard (SVG) is used to describe non-rectangular, and rotated rectangular, areas of canvas or image resources. In this pattern, the resource of the annotation is a “oa:SpecificResource” which has the complete image referenced in a full field and the SVG embedded in a selector field (as the SVG selects the part of the image needed). The SVG document is embedded using the same ContentAsText approach as for embedding comments or transcriptions.

If the section of an image is mapped to part of a canvas, as in the example below, then the target in on must be the rectangular bounding box in which the SVG viewport should be placed. If the entire canvas is the target, then the SVG viewport is assumed to cover the entire canvas. If the dimensions of the viewport and the bounding box or canvas are not the same, then the SVG must be scaled such that it covers the region. This may result in different scaling ratios for the X and Y dimensions.

SVG should not be used to describe non-rotated rectangular regions. The IIIF Image API or the xywh bounding box described above should be used instead.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@type": "oa:SpecificResource",
    "full": {
      "@id": "http://example.org/iiif/book1/res/page1.jpg",
      "@type": "dctypes:Image"
    },
    "selector": {
      "@type":["oa:SvgSelector","cnt:ContentAsText"],
      "chars": "<svg xmlns=\"...\"><path d=\"...\"/></svg>"
    }
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,100,300,300"
}

6.5. Style

The Cascading Style Sheets standard (CSS) is used to describe how the client should render a given resource to the user. The CSS information is embedded within the annotation using the same ContentAsText approach above. As a stylesheet may contain more than one style, and be reused between annotations, it is attached to the annotation directly in the same manner as a stylesheet being linked to an HTML document. Then the name of the style class is attached to the resource that should be styled, again in the same manner as the class attribute in html, although we use style to avoid confusion with object classes.

In the example below, the text should be colored red.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "stylesheet":{
    "@type": ["oa:CssStyle", "cnt:ContentAsText"],
    "chars": ".red {color: red;}"
  },
  "resource":{
    "@type": "oa:SpecificResource",
    "style": "red",
    "full": {
      "@type": "cnt:ContentAsText",
      "chars": "Rubrics are Red, ..."
    }
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,150,500,30"
}

6.6. Rotation

CSS may also be used for rotation of images which are not correctly aligned with the canvas. In the example below, after the image is located within the 500 wide by 30 high space within the canvas, it is then rotated by the rendering client application around the top left corner by 45 degrees anti-clockwise.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "stylesheet":{
    "@type": ["oa:CssStyle", "cnt:ContentAsText"],
    "chars": ".rotated {transform-origin: top left; transform: rotate(-45deg);}"
  },
  "resource":{
    "@type": "oa:SpecificResource",
    "style": "rotated",
    "full": {
      "@id": "http://example.org/iiif/book1/res/page1-detail.png",
      "@type": "dctypes:Image"
    }
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=100,150,500,30"
}

Alternatively, if the image is available via the IIIF Image API, it may be more convenient to have the server do the rotation of the image. This uses a custom Selector for the Image API, further described in the Open Annotation extensions annex. For the purposes of rotation, the example below demonstrates the pattern.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "sc:painting",
  "resource":{
    "@id": "http://example.org/iiif/book1-page1/full/full/90/default.jpg",
    "@type": "oa:SpecificResource",
    "full": {
      "@id": "http://example.org/iiif/book1-page1/full/full/0/default.jpg",
      "@type": "dctypes:Image",
      "service": {
        "@context": "http://iiif.io/api/image/2/context.json",
        "@id": "http://example.org/iiif/book1-page1",
        "profile": "http://iiif.io/api/image/2/level2.json"
      }
    },
    "selector": {
      "@context": "http://iiif.io/api/annex/openannotation/context.json",
      "@type": "iiif:ImageApiSelector",
      "rotation": "90"
    }
  },
  "on": "http://example.org/iiif/book1/canvas/p1#xywh=50,50,320,240"
}

6.7. Comment Annotations

For annotations which are comments about the canvas, as opposed to painting content resources onto the canvas, there are different types of motivation to make the distinction clear. For annotations about the content (such as comments, notes, descriptions etc.) the motivation should be “oa:commenting”, but may be any from the list given in the Open Annotation specification.

Unlike painting annotations, comments or annotations with other motivations should have a URI assigned as their identity and provided in the @id property. When dereferencing that URI, the representation of the annotation should be returned. This is to allow further annotations to annotate the comment, for example in order to reply to it, or to tag it for organizational or discovery purposes.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/annotation/anno1",
  "@type": "oa:Annotation",
  "motivation": "oa:commenting",
  "resource":{
    "@id": "http://example.org/iiif/book1/res/comment1.html",
    "@type": "dctypes:Text",
    "format": "text/html"
  },
  "on": "http://example.org/iiif/book1/canvas/p1"
}

Other resources may also have comments made about them, including manifests (comments about the object), sequences (comments about that particular ordering), ranges (comments about the section), annotations (replies to the targeted annotation), and so forth. In order for the client to discover these annotations, they can be included in an AnnotationList referenced from the target resource. This is accomplished by reusing the otherContent pattern. Any resource may have a list of annotations associated with it in this way.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id": "http://example.org/iiif/book1/manifest",
  "@type": "sc:Manifest",
  // ...

  "otherContent": [
    {
      "@id": "http://example.org/iiif/book1/list/book1",
      "@type": "sc:AnnotationList"
    }
  ]
}

6.8. Hotspot Linking

It is also possible to use annotations to create links between resources, both within the manifest or to external content. This can be used to link to the continuation of an article in a digitized newspaper in a different canvas, or to link to an external web page that describes the diagram in the canvas.

Hotspot linking is accomplished using an annotation with a motivation of “oa:linking”. The region of the canvas that should trigger the link when clicked is specified in the on field in the same way as other annotations. The linked resource is given in the resource field. The linked resource may also be another canvas or region of a canvas. The user experience of whether the linked resource is opened in a new tab, new window or by replacing the current view is up to the implementation.

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@id":"http://www.example.org/iiif/book1/annotation/anno1",
  "@type":"oa:Annotation",
  "motivation":"oa:linking",
  "resource": {
    "@id":"http://www.example.org/page-to-go-to.html",
    "@type":"dctypes:Text",
    "format":"text/html"
  },
  "on":"http://www.example.org/iiif/book1/canvas/p1#xywh=500,500,150,30"
}

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

7.1. Requests

Each of the entries in section 4 recommends a URI pattern to follow for the different resources. Following these patterns is NOT REQUIRED and clients must not construct the URIs by themselves, instead they must follow links from within retrieved descriptions.

The Base URI, to which additional information is appended, that is recommended for resources made available by the API is:

{scheme}://{host}{/prefix}/{identifier}

Where the parameters are:

Name Description
scheme Indicates the use of the http or https protocol in calling the service.
server The host server (and optional port) on which the service resides.
prefix The path on the host server to the service. This prefix is optional, but may be useful when the host server supports multiple services. The prefix may contain multiple path segments, delimited by slashes, but all other special characters must be encoded.
identifier The identifier for the object or collection, expressed as a string. This may be an ark, URN, or other identifier. Special characters must be URI encoded.

The individual resources should have URIs below this top-level pattern, formed by appending a “/” and additional information to identify the resource. Recommended patterns for these URIs are given in the sections below for the different resource types, and summarized in Appendix A.

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. While this does not follow the recommended URI patterns below, it is not prevented by the specification either.

7.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).

Content-Type: application/ld+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.

8. 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

Resource URI Pattern
Collection {scheme}://{host}/{prefix}/collection/{name}
Manifest {scheme}://{host}/{prefix}/{identifier}/manifest
Sequence {scheme}://{host}/{prefix}/{identifier}/sequence/{name}
Canvas {scheme}://{host}/{prefix}/{identifier}/canvas/{name}
Annotation {scheme}://{host}/{prefix}/{identifier}/annotation/{name}
AnnotationList {scheme}://{host}/{prefix}/{identifier}/list/{name}
Range {scheme}://{host}/{prefix}/{identifier}/range/{name}
Layer {scheme}://{host}/{prefix}/{identifier}/layer/{name}
Content {scheme}://{host}/{prefix}/{identifier}/res/{name}.{format}

B. 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 viewingDirection viewingHint 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 optional
Annotation recommended
AnnotationList required
Range optional
Layer optional
Image Content required
Other Content required

C. Example Manifest Response

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

{
  "@context": "http://iiif.io/api/presentation/2/context.json",
  "@type": "sc: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": "https://creativecommons.org/publicdomain/zero/1.0/",
  "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": "sc:Sequence",
        "label": "Current Page Order",
        "viewingDirection": "left-to-right",
        "viewingHint": "paged",
        "canvases": [
          {
            "@id": "http://example.org/iiif/book1/canvas/p1",
            "@type": "sc:Canvas",
            "label": "p. 1",
            "height":1000,
            "width":750,
            "images": [
              {
                "@type": "oa:Annotation",
                "motivation": "sc: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": "sc:AnnotationList",
                "within": {
                    "@id": "http://example.org/iiif/book1/layer/l1",
                    "@type": "sc:Layer",
                    "label": "Example Layer"
                }
              }
            ]
        },
          {
            "@id": "http://example.org/iiif/book1/canvas/p2",
            "@type": "sc:Canvas",
            "label": "p. 2",
            "height":1000,
            "width":750,
            "images": [
              {
                "@type": "oa:Annotation",
                "motivation": "sc: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": "sc:AnnotationList",
                "within": "http://example.org/iiif/book1/layer/l1"  
              }
            ]
          },
          {
            "@id": "http://example.org/iiif/book1/canvas/p3",
            "@type": "sc:Canvas",
            "label": "p. 3",
            "height":1000,
            "width":750,
            "images": [
              {
                "@type": "oa:Annotation",
                "motivation": "sc: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": "sc:AnnotationList",
                "within": "http://example.org/iiif/book1/layer/l1"               
              }
            ]
          }
        ]
      }
    ],
  "structures": [
    {
      "@id": "http://example.org/iiif/book1/range/r1",
        "@type": "sc: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"
        ]
    }
  ]
}

D. Implementation Notes

  • Clients should be aware that some implementations may add an @graph property at the top level, which contains the object. This is a side effect of JSON-LD serialization, and servers should remove it before sending to the client. If this is seen in practice, the client can use the JSON-LD compaction algorithm and JSON-LD Framing with the supplied frames to remove it and generate the correct representation.

  • If a {name} parameter in the recommended URI structure begins with a number, such as .../canvas/1, then developers using certain technology stacks may be inconvenienced. In particular, an RDF based stack that uses RDF/XML internally will not be able to derive a shared .../canvas/ prefix and then use the 1 as a CURIE, as <canvas:1> is not a valid element in XML. Producers might consider adding an alphabetical character as the initial character.

E. Versioning

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

F. 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.

G. Change Log

Date Description
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)