This document is a companion to the IIIF Image API Specification, Version 2.1. It describes the significant changes to the API since Version 2.0. The changes are broken into three groups: Non-breaking Changes, i.e. those that are backwards compatible from client or server perspectives; Deprecations and Deferred Changes, i.e. those that will be made in a future iteration of the Image API.
square region keyword selects a region where the width and height are both equal to the length of the shorter dimension of the complete image. The region may be positioned anywhere in the longer dimension of the image content at the server’s discretion, and centered is often a reasonable default. The corresponding feature name
regionSquare has also been added to the profile description. It is an open question whether support for
square will become mandatory at levels 1 and 2 in the next major version of the Image API. See issue 425, issue 560, and issue 501.
Rights and Licensing Properties
logo properties have been added to the Image Information. They have the same semantics and requirements as the properties of the same names in the Presentation API. See issue 227 and note also deferred change of the JSON-LD tag name from
Version 2.0 incorrectly recommended the inclusion of a HTTP link header for the JSON-LD context, which was unnecessary as the
@context key in the JSON document would override it. Therefore, the description of the Image Information Request no longer includes this. See issue 556.
New feature names
sizeByDistortedWh in the profile description provide clear indications of support for
!w,h and distorting
w,h size requests respectively. As a result the related feature names
sizeByForcedWh have been deprecated. See issue 720 and additional discussion on pull pequest 727.
The size keyword
max may be used to request that the image or region is returned at the maximum size available, as indicated by
maxArea properties. See issue 663 and the related deprecation of the size keyword
The size keyword
full will be replaced by
max in version 3.0. It is impractical to deliver the full size of very large images, and thus the keyword is not helpful when the Image Information has not been read. When the Image Information has been read, clients can request the explicit
w,h size. See issue 678.
The feature names
sizeByForcedWh will be removed from the profile description in version 3.0. The feature
sizeByForcedWh was inconsistently defined in version 2.0. The feature
sizeByWhListed is implied by including
sizes in the image information document and is therefore not required as a named feature. See issue 720 and related addition of
The canonical URI syntax will change in the next major release to use the
w,h size syntax in a manner compatible with the
sizes array, and to use
max instead of
full as the size keyword. See issue 554 and issue 678.
The mapping of the
license property has already been changed to
dcterms:rights in the JSON-LD context to more accurately represent its use for both rights and licensing information. However, the change of the property name will be a breaking change and thus must wait for the next major version release. See issue 644.