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.
1. Non-breaking Changes
1.1. Added square Region
The 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.
1.2. Added Rights and Licensing Properties
Rights and Licensing Properties attribution, license and 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 license to rights.
1.3. Removed Recommendation to include HTTP Link Header to JSON-LD Context
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.
1.4. Added sizeByConfinedWh and sizeByDistortedWh Feature Names
New feature names sizeByConfinedWh and 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 sizeByWhListed and sizeByForcedWh have been deprecated. See issue 720 and additional discussion on pull pequest 727.
1.5. Added maxWidth, maxHeight and maxArea Properties
The maxWidth, maxHeight and maxArea properties in the profile description provide a way for image servers to express the limits on its supported sizes for image requests. See issue 620.
1.6. Added max Size Keyword
The size keyword max may be used to request that the image or region is returned at the maximum size available, as indicated by maxWidth, maxHeight and maxArea properties. See issue 663 and the related deprecation of the size keyword full.
2. Deprecations
2.1. Deprecated Size Keyword full
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.
2.2. Deprecated sizeByWhListed and sizeByForcedWh Feature Names
The feature names sizeByWhListed and 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 sizeByConfinedWh and sizeByDistortedWh.
3. Deferred Changes
3.1. Change Canonical Syntax
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.
3.2. Change license property name to rights
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.