This document is a companion to the IIIF Presentation API Specification, Version 3.0. It describes the changes to the API specification made in this major release, including ones that are backwards incompatible with version 2.1.1, the previous version.
Table of Contents
- 1. Breaking Changes
- 1.1. External Specifications
- 1.2. Property Naming and Semantics Changes
- 1.2.1. Rename
- 1.2.2. Rename
- 1.2.3. Rename
- 1.2.4. Consolidate structural properties to
- 1.2.5. Rename
- 1.2.6. Rename
- 1.2.7. Rename
- 1.2.8. Rename
- 1.2.9. Rename
start, allow reference to part of a Canvas
- 1.2.10. Rename
- 1.2.11. Specify interaction and inheritance model for
- 1.2.12. Wrap
logoin a structure with more information, introduce
- 1.2.13. Remove
- 1.2.14. Update context for new major version
- 1.2.1. Rename
- 1.3. Property Value Changes
- 1.3.1. Allow long texts in
- 1.3.2. Allow non-images in
- 1.3.3. Use language map pattern for
- 1.3.4. Always require arrays if property can have multiple values
- 1.3.5. Require a JSON object for all non-enumerable resources
- 1.3.6. Canvases always include AnnotationPages, not Annotations directly
- 1.3.7. Change requirements for
- 1.3.1. Allow long texts in
- 1.4. Classes Changes
- 1.5. Requirements Changes
- 2. Non-Breaking Changes
- 2.1. Enable Audio and Video Content
- 2.1.1. Allow Canvases to be treated as Content Resources
- 2.1.2. Add
placeholderCanvasfor associated content
- 2.1.3. Add
- 2.1.4. Add
- 2.1.5. Add
- 2.1.6. Add
- 2.1.7. Add
- 2.1.8. Reference external Selectors
- 2.2. Additional Features
- 2.3. Protocol Features
- 2.1. Enable Audio and Video Content
- 3. Editorial Changes
- 3.1. Clarifications
- 3.1.1. Add explicit definition of
- 3.1.2. Clarify “referenced” and “embedded”
- 3.1.3. Clarify patterns for cross-version references
- 3.1.4. Clarify
@graphis just not allowed
- 3.1.5. Clarify no interstitial pages for
- 3.1.6. Clarify
multi-partcollections can have sub-collections
- 3.1.7. Clarify case-sensitivity of terms
- 3.1.1. Add explicit definition of
- 3.2. Style
- 3.1. Clarifications
1. Breaking Changes
1.1. External Specifications
1.1.1. Use JSON-LD 1.1
JSON-LD remains the core serialization of the Presentation API. For version 3.0, some features of the JSON-LD Community Group specification make a significant improvement to the API’s structure and consistency. While this specification is not a W3C Technical Recommendation at the time of release, the likelihood of the standardization process being successful is extremely high and the rewards have been judged to be worth the minimal risk of unintended incompatibility. Scoped contexts, language sets, and the ability to use
@none in language maps make implementation significantly easier. See issue #1192.
1.1.2. Use Web Annotation Data Model
Annotations remain a core feature of the Presentation API. Instead of the community specified Open Annotation model, version 3.0 adopts the W3C standard Web Annotation Data Model. The practical effects are limited but real, including changes to property names and classes, and introducing some slight inconsistencies between IIIF properties and Web Annotation Data Model properties. See issue #496, #1764.
1.2. Property Naming and Semantics Changes
Several existing properties were renamed for consistency, developer convenience, or to better reflect the intended semantics. Some of the semantics were also clarified based on implementation experience from previous versions.
manifest.id) instead of the square-brackets-based equivalent needed with the
@ character (
manifest['@id']). This follows JSON-LD community best practices established by schema.org, the JSON-LD, Web Annotation and Social Web working groups. See issue #590.
viewingHint property was renamed to
behavior as it was felt this more accurately reflected the intent, and avoids the image specific “viewing” which would be inappropriate for audio only content. As
viewingDirection is inherently spatial, it was not renamed. The “hint” part was removed as some behaviors are very important to respect. See issue #1073.
attribution property could not specify the label to render with the value, and thus clients typically used “Attribution”. This was not able to be internationalized, nor changed in contexts where “Attribution” has specific meaning (such as for artworks, where the attribution is assignment of the creator). The structure was changed to allow both
metadata entries, to solve this and the property renamed to remove the rights-specific semantics. See issue #1287.
1.2.4. Consolidate structural properties to
items where possible
The Presentation API classes in version 2.1.1 had both
members to allow for mixed class lists (e.g. a Range can include both Canvases and other Ranges) and properties that were class specific. The
members properties were renamed to
items to follow the pattern established in the Web Annotation Data Model and ActivityStreams. The class specific properties were removed completely as insufficient to cover important use cases, and no longer necessary. See issue #1145.
license property was renamed to the more general
rights to accommodate both rights statements and usage licenses. The value was further constrained to allow only
http Creative Commons URIs,
https RightsStatements.org URIs, and any URI registered as an extension. This additional constraint is to allow clients to treat the property as an enumeration rather than free text, and implement URI specific behavior. See issues #644, #1479, and #1874 which was approved by trc#32.
description property was renamed to
summary and the semantics changed to be a short descriptive text. The new property is a replacement for the content in
metadata, for situations when a a table of label/value pairs is too much to render. Descriptions that are not short descriptive text are now recorded in
metadata to allow for appropriate labeling. See issue #1242 and entry 1.3.1 below.
Similar to the above changes where non-actionable links and content are put into
related property was renamed to
homepage with more specific semantics of being the home page of the resource. Links to other resources instead go in to
metadata as HTML. Multiple homepages are allowed per resource, but they should represent different language or format representations of the same content. See issues #1286, #1484, #1760. Approved by trc#4.
With the removal of the
Layer class in favor of the standard
AnnotationCollection, and the introduction of the
contentLayer property was renamed to
supplementary. This conveys that the Annotations in the Annotation Collection are those with the
supplementing while avoiding the use of the defunct class name. See issues #1480 and #1174.
start, allow reference to part of a Canvas
Following the pattern of removing class names from property names when unnecessary, combined with the change that the referenced resource might be part of a Canvas rather than the entire Canvas, the property was renamed. The increased scope for parts of Canvases is to allow jumping to a specific time point within a Canvas with a
duration property. See issues #1320 and #1930.
While renaming properties,
within was renamed to
partOf to follow the same naming convention in ActivityStreams and the Web Annotation Data Model. See issue #1482.
1.2.11. Specify interaction and inheritance model for
The specification now mandates an inheritance model for behaviors across classes, and is clear about which behaviors can be asserted on the same resource. This clarifies the implementation expectations for clients and publishers alike, and prevents different implementers from making very different choices about how to present the same information. See issues #1612 and #1643. Approved by trc#13 and trc#16.
logo in a structure with more information, introduce
Previously, the APIs allowed for a
logo property for referencing the logos of institutions that somehow contributed or needed acknowledgement. There was no way, however, to associate a label with the logo and this was magnified by the change from
requiredStatement. The solution adopted is to introduce a
provider property that has a full structure to represent information about providing people or organizations, including
homepage and others. See issues #1639, #1698, #1759, #1777, #1924. Approved by trc#3 and trc#7.
otherContent property, use
otherContent property was used to link from Canvas and Layer resources to Annotation Lists containing transcriptions, video, audio or commentary. Such annotations are now included in Annotation Pages linked via the
annotations property from Canvas resources, and via
items from Annotation Collection resources respectively. These annotations may have various non-
painting motivations, including the
supplementing motivation for transcriptions. See issue #1262.
1.2.14. Update context for new major version
The URI of the context document was updated for the new major version, and thus the value of the
@context is either the new value
http://iiif.io/api/presentation/3/context.json, or includes this as the last item in an array value.
1.3. Property Value Changes
1.3.1. Allow long texts in
Several use cases were raised for long texts that were not descriptions, such as bibliography citation lists or provenance histories for artworks. These texts did not have a home in the previous versions, as
metadata only allowed short values and
description was a description of the object not information about it. The adopted solution was to allow long texts within
metadata values, and to replace
summary, now more specifically a short textual summary. See issue #1270
1.3.2. Allow non-images in
The semantics of
thumbnail were changed to allow for non-image content resources such as short audio or video files. This is important with the addition of time-based media being painted into Canvases. See issue #1176.
1.3.3. Use language map pattern for
A new pattern has been adopted for all textual values of a JSON object with the language code as the key (or
none if the language is not known) and the content as a string within an array as the value. This pattern is much easier to implement and use than the previous
@language tuples pattern. See issues #755 and #1739. Approved by trc#2, trc#5 and trc#26.
1.3.4. Always require arrays if property can have multiple values
Previous versions allowed a property that allowed multiple values to express a single value without an array. From version 3.0, if a property can ever have multiple values, then the value of the property is always an array. This reduces the type checking needed on values by clients as they can always iterate over the array, improving the developer experience. See issue #1131.
1.3.5. Require a JSON object for all non-enumerable resources
Similarly, to reduce type checking, all resources where the URIs cannot be enumerated (such as behaviors, viewing directions, rights statements, and so forth) must be expressed as a JSON object with at least the
type properties. This further reduces the type checking needed, as previously it could have been just the URI as a string. See issue #1284.
1.3.6. Canvases always include AnnotationPages, not Annotations directly
For consistency, and to allow all content to be external to the Manifest, all Annotations are now only included via
AnnotationPage resources. This is a change from previous versions, where image Annotations were included directly to Canvases using
images. See issue #1068.
1.3.7. Change requirements for
Previously the value of
navDate was required to be in the UTC timezone. However this meant that the navigation date text generated was sometimes not the same date as the resource due to when midnight occurs in the local timezone versus in UTC. The solution adopted was to allow any timezone to be given in the value. See issue #1296.
1.4. Classes Changes
1.4.1. Remove Sequence in favor of Ranges,
There has been a long outstanding question of how the order of Canvases in the
items of Ranges and the order in the current Sequence interact. With further implementations from outside of the initial library-oriented domain, the need for an explicit order for views is also greatly decreased. The initial use case of multiple orderings for the content remains valid, but an edge case that can be supported using other patterns rather than requiring every Manifest to have an explicitly named Sequence. The replacement is a new
behavior value or
sequence. The model is simplified and clarified by this removal. See issues #1471, #1489 and further issues referenced from those.
1.4.2. Ranges express full extent
In previous versions, it was unclear whether Ranges were intended to capture the extent of the content or simply the hierarchy. This is particularly important with time-based media, as the intent is not to skip between the navigation entry points when rendering the Range, but instead to play continuously. However a Range that captures the discrete sections of newspaper pages that make up an article does not include all of the intervening content. This difference was reconciled by requiring Ranges to include all and only Canvases or segments of Canvases that are strictly part of the Range. At the same time, the structure was made easier to process by embedding child ranges within the parent, rather than referencing within a flat list. See issue #1070 and the referenced documentation.
1.4.3. Remove Layer, AnnotationList in favor of AnnotationCollection, AnnotationPage
With the adoption of the Web Annotation Data Model, we remove the IIIF specific Layer in favor of the standard AnnotationCollection, and AnnotationList in favor of the equivalent AnnotationPage. See issue #496.
1.4.4. Remove paging functionality
As the Web Annotation Data Model defines the paging model, and Collection paging was neither implemented nor especially different from simply having a hierarchy of Collections, paging functionality was removed from the API. This simplifies the model at no cost. See issue #1343.
1.4.5. Move “advanced” Annotation features to cookbook
The number of possible uses of the Web Annotation Data Model within the context of the Presentation API is extremely high. The previous section 6 of version 2.0 and 2.1 was removed in favor of entries in a “cookbook” that could be expanded and adapted over time, rather than as a specification process. This separation makes new use cases easier to accommodate and describe solutions for, without producing new minor versions of the specification.
1.5. Requirements Changes
1.5.1. Establish client requirements per property
It was previously unclear which properties clients were required to process, and which could be left unimplemented without severely affecting the user experience of resources that made use of the properties. Requirements have been added per class/property combination. See issues #1243 and #1271
1.5.2. Canvas should have
Not every view of an object has a defined label, or can have one automatically generated. As such, in order to conform with the previous requirement that Canvases must have labels, implementers were adding empty or invisible labels as a workaround. In version 3.0,
label on Canvas is only recommended rather than required. See issue #964
1.5.3. Resources referenced from Collections should have
With the clarification that Collections are exclusively for navigation and not discovery, their use in user interfaces was improved by recommending the inclusion of
thumbnail on referenced resources. See issue #1502.
1.5.4. Requirements of
type property with a single value is now required on all resources, including content resources and services. This serves several purposes, including facilitating object mapping code libraries, clarity about the rendering needs for the resource given the new inclusion of audio and video as core content, and forcing the serialization to generate a JSON object for the resource, not just a string with the resource’s URI. The values of
type were enumerated for content resources. See issues #1676, #1677 and #1147. Approved in part by trc#27.
2. Non-Breaking Changes
2.1. Enable Audio and Video Content
2.1.1. Allow Canvases to be treated as Content Resources
Canvases may be treated as content resources for the purposes of annotating on to other Canvases. For example, an excerpt of a Canvas that contains a video resource and annotations representing subtitles may be annotated on to another Canvas; the relative spatial and temporal alignment of the video and subtitles will be maintained. See issue #1191, previously #42.
placeholderCanvas for associated content
Many time-based media presentations have additional content associated with the object, such as either a poster that is rendered while video is buffering or on a selection user interface (
placeholderCanvas), or images that might be displayed while an audio-only object is being rendered (
accompanyingCanvas). The addition of these properties allows the content to be associated with the resource while not being part of the object directly. The rendering requirements for these Canvases are different from Canvases that represent the object, including that they cannot have their own accompanying or placeholder Canvases in a recursive structure. See issues #1263, #1605 and #1615. Approved by trc#8.
duration on Canvas
In order to have time-based media associated with a Canvas, the Canvas needs to have a duration dimension. This was added to allow multiple video and/or audio files to be synchronized in time in the same way that Image (and Video) files can be aligned in the spatial dimensions. See issues #1069 and #1190.
timeMode on Annotation
timeMode indicates whether the client should
loop playback of content resources with a time component when those resources are not identical in length to the duration of the portion of the Canvas onto which they are annotated. See issue #1075.
In some cases it may be desirable to have playback advance automatically from one Canvas, or part thereof, to the next, such as when Canvases represent tracks of an album; the
behavior enables this. The
no-auto-advance behavior would then turn it off, if
auto-advance has been inherited. See issues #1583 and #1632. Approved by trc#17.
Ranges may be used to present navigation based on thumbnails, such as video keyframes displayed in a timeline. The
behavior on a Range indicates it is not to be displayed in a conventional table of contents. See issue #1259.
behavior indicates that the playback order of a Collection or Manifest containing temporal Canvases should return to the first Canvas after reaching the end of the final Canvas of the resource. The
no-repeat behavior would then turn it off, if
repeat has been inherited. See issue #1328.
2.1.8. Reference external Selectors
New content type specific Selectors for the Web Annotation Data Model are needed in order to refer to points (rather than ranges) within image, audio and video content. Similarly, there is a need to select all Audio or Visual content from within a multi-media resource. These Selectors (
VideoContentSelector) are defined in an annex, and referenced from the specification. See issue #1593.
2.2. Additional Features
language on external resources
A number of behaviors are introduced to accommodate new user interaction requirements. The
behavior can be used to suppress the display of a Range that is not intended for user navigation. The
behavior is valid on Annotation Collections, Annotation Pages, Annotations, Specific Resources and Choices and indicates that the resource should by default not be rendered. The
behavior indicates that the resource’s Canvases do not have an inherent order. See issues #1070, #1417 and #1679. Approved by trc#14.
behavior, valid on Collections, was introduced to indicate to clients that child Manifests, for example those containing a musical score and a related recording, should be presented simultaneously.
motivation does not permit sufficient flexibility in the display of annotation content derived from the Canvas, such as a transcription of text in an image or the words spoken in an audio representation. Annotations with the
supplementing may be displayed as part of the Canvas representation or in a separate area of the user interface. See issues #1258, #1480 and #1738.
paged behavior on Collections with
services property for Collections and Manifests
Some services are used multiple times within a single Collection or Manifest, such as IIIF Authentication services. These were difficult to find or overly verbose to repeat for every usage. The
services property was added to the top level resources that can collect these multiply referenced services in a single, easy-to-find location. See issue #1873. Approved by trc#31.
2.3. Protocol Features
2.3.1. Define JSON-LD profile for media type
A specific media-type, to be used with the HTTP headers
Content-Type was defined. This media type is the JSON-LD media type, with the context in the
profile parameter, following established conventions. See issue #1066.
2.3.2. Remove per-class URI patterns, instead make general recommendations
The URI patterns given in earlier versions were removed as unhelpful. They were replaced with section 6.1. that makes general best practice recommendations about the form of URIs, including the use of the HTTPS scheme and protocol. See issue #1214.
2.3.3. Allow external Ranges
In previous versions, Ranges were required to be embedded within the Manifest. With the removal of Sequences, this means that Ranges must be allowed to be referenced resources from the Manifest and thus separately requested. An additional use case comes from the AV work, where a Range could give a large set of thumbnails for every keyframe of a video to be presented on a scrubbing bar (see the
thumbnail-nav value for
behavior). It would be overwhelming to include this in the Manifest directly. See issue #1218.
2.3.4. Recommend HEAD functionality
2.3.5. Clarify content negotiation expectations
Expectations around the implementation of content negotiation were added. See issue #1685.
3. Editorial Changes
3.1.1. Add explicit definition of
In previous versions,
profile was mentioned but never formally defined. This has now been defined explicitly. See issue #1276.
3.1.2. Clarify “referenced” and “embedded”
The terms “referenced” and “embedded” were never defined, but used in dozens of places. These are now defined explicitly. See issue #1396.
3.1.3. Clarify patterns for cross-version references
With significant breaking changes, it was necessary to clarify that the representations of resources that are in divergent versions retain the features of the version they were defined in, even when referenced from the diverging version’s resources. See issue #1064.
@graph is just not allowed
Previously it had been noted in an implementation note that clients might encounter the
@graph key in the JSON-LD, but that publishers had to strip it out. This has been clarified that
@graph is simply not allowed in the IIIF Presentation API. See issue #920.
3.1.5. Clarify no interstitial pages for
Some organizations had a desire to include a web page between the manifest and the
rendering resource, such as a terms and conditions for download agreement. It was clarified that this is not allowed, and instead the IIIF Authentication API would serve this use case. See issue #1155.
multi-part collections can have sub-collections
The text was not clear as to whether Collections can be members of a Collection that has the behavior value
multi-part, or if only Manifests are valid. It was clarified that both Manifests and Collections can be present. See issue #1633. Approved by trc#10.
3.1.7. Clarify case-sensitivity of terms
It was clarified that all terms in the JSON are case sensitive, and must be represented exactly as given in the specification. See issue #1703
3.2.1. Restructure document
The document was again fundamentally restructured for clarity, and to remove non-core content that simply described how to make use of external specifications, and especially Web Annotations, to a cookbook. This enables additional use cases and patterns to be documented without requiring a new version of the specification to describe something that is already possible. It can be managed by the community, rather than via the more rigorous specification process.
The use of
code font and capitalization was made consistent for class names, property names and values when used in prose. References to them in lists, especially for implementation requirements, were made consistent.
3.2.3. Visual Appearance
The CSS and icons used in the requirements tables were improved, and the information updated.
3.2.4. Examples Improved
The examples were improved to be more intuitive, and cover more of the features available.