IIIF Image API Changes: v2.1.1 -> v3.0

class: center, middle
class: center, middle

# IIIF Image API Changes: v2.1.1 -> v3.0

Simeon Warner (Cornell University)

Revised version of slides first presented at
[2018 IIIF Conference](http://iiif.io/event/2018/washington/), Washington, DC. 2018-05-24

![Washington Conference Logo](http://iiif.io/img/washington_logo.png)
---
class: middle

# Breaking Changes

Changes that are not backwards compatible with 2.1.1. Implementations must be updated in order to support these changes

Later:

* Non-Breaking Changes - optional additions (not many)
  * Editorial -  mostly clarifications

---

## Breaking: Remove size `full` in favor of `max`

* `full` was [deprecated in 2.1.1](http://iiif.io/api/image/2.1/#full-dep)
  * `full` is no longer allowed for the size parameter
  * `max` must be used instead
    * might not have same meaning
    * MUST be supported (`full` might have been too large)

.pull-left.v211[``` bash
.../img123/full/full/0/default.jpg
```]

.pull-right.v30[``` bash
.../img123/full/max/0/default.jpg
```]

.refs[(issues [#678](https://github.com/IIIF/api/issues/678), [#1369](https://github.com/IIIF/api/issues/1369))]

---

## Breaking: Use _`w,h`_ as canonical form of size parameter

* 2.1.1: was _inconsistent_ in specification of preferred `sizes` in `info.json`, and requests using the _`w,`_ canonical form
  * 3.0: canonical form of size is either:
    * `max` if the maximum size is requested
    * _`w,h`_ form

``` json
  "sizes": [ { "width": 123, "height": 456 }, ... ]
```

with above `sizes` the the canonical request for this preferred size is:

.pull-left.v211[``` bash
.../img123/full/123,/0/default.jpg
```]

.pull-right.v30[``` bash
.../img123/full/123,456/0/default.jpg
```]

.refs[(issues [#544](https://github.com/IIIF/api/issues/544) and [#678](https://github.com/IIIF/api/issues/678))]

---

## ... and canonical form of size parameter affects tile requests

Consider the request for a 512 by 512 tile from a 1024 by 1024 region of an image:

.v211[``` bash
.../img123/1024,2048,1024,1024/512,/0/default.jpg
```]

.v30[``` bash
.../img123/1024,2048,1024,1024/512,512/0/default.jpg
```]

or tile at the right edge (where full size is 5000 pixels wide):

.v211[``` bash
.../img123/4096,2048,14,1024/7,/0/default.jpg
```]

.v30[``` bash
.../img123/4096,2048,14,1024/7,512/0/default.jpg
```]

---

## Breaking: Size parameter value must not scale image to larger than the extracted region

* 2.1.1 optionally allowed size to [scale up image](http://iiif.io/api/image/2.1/#size)
  * now:
    * requests to scale up MUST generate an error
    * `sizeAboveFull` feature name removed

Consider a request to extract 10 by 10 region and scale up to 100 by 100:

``` bash
https://example.org/img123/0,0,10,10/100,100/0/default.jpg
```

* 2.1.1 -- 100 by 100 result or ERROR
  * 3.0 -- **4xx ERROR**

.refs[(issues [#693](https://github.com/IIIF/api/issues/693) and [#1370](https://github.com/IIIF/api/issues/1370))]

---

## Breaking: Rename `@id` to `id`, `@type` to `type`

* `image.id` instead of `image['@id']` in Javascript 
  * follow JSON-LD community best practices established by schema.org, the JSON-LD, Web Annotation and Social Web working groups
  * same in Presentation API
  * only remaining `@` is in `@context`

.pull-left.v211[``` json
{
  "@context" : "http://iiif.io/api/image/2/context.json",
  "@id": "https://...",
  ...
```]

.pull-right.v30[``` json
{
  "@context": "http://iiif.io/api/image/3/context.json",
  "id": "https://...",
  "type": "ImageService3",
  ...
```]

.refs[(issue [#590](https://github.com/IIIF/api/issues/590))]

---

## Breaking: Rename `attribution` to `requiredStatement`, allow `label`+`value`

* 2.1.1: `attribution` property
    * could not specify the label to render with the value (clients typically used "Attribution"), not right in all contexts
    * could not internationalize label
  * 3.0: renamed to **`requiredStatement`**
    * removes the rights-specific semantics
    * allows specification and internationalization of both **`label`** and **`value`**

.pull-left.v211[
``` json
  "attribution": "Provided by ...", 
```]

.pull-right.v30[
``` json
  "requiredStatement": {
    "label": { ... },
    "value": { ... }
  }
```]

.refs[(issues [#1287](https://github.com/IIIF/api/issues/1287) and [#1415](https://github.com/IIIF/api/issues/1415))]

---

## ... and use language map pattern

* As in Presentation API, new pattern for all textual values:
    * JSON object
    * language code as the key (or `@none` if language is not known)
    * content as one or more strings within an array as the value
    * applied only `requiredStatement` in Image API
    * **N.B. -- ERROR IN EXAMPLES IN ALPHA DRAFT**

.v30[``` json
 "requiredStatement": {
 "label": {
 "en": [ "Attribution" ],
 "cy": [ "Priodoliad" ]
 },
 "value": {
 "en": [ "Provided by Organization" ],
 "cy": [ "Darparwyd gan Sefydliad" ]
 }
 }
```]

.refs[(issue [#755](https://github.com/IIIF/api/issues/755))]

---

## Breaking: `license` -> `rights`

* `license` property renamed to `rights`
  * accommodate both rights statements and usage licenses
  * value MUST be a single URI, an array is no longer permitted
  * further constrained to Creative Commons URIs, RightsStatements.org URIs and URIs registered as extensions
  * clients to understand as an enumeration rather than free text, and implement URI specific behavior

.v211[
``` json
  "license": "http://rightsstatements.org/vocab/InC-EDU/1.0/"
```]

.v30[
``` json
  "rights": "http://rightsstatements.org/vocab/InC-EDU/1.0/"
```]

.refs[(issues [#644](https://github.com/IIIF/api/issues/644) and [#1479](https://github.com/IIIF/api/issues/1479))]

---

## Breaking: Require an array of JSON objects for the `logo` property

* 2.1.1: `logo` single or array value, each with string or JSON object contents
  * 3.0: `logo` always an array of JSON objects (even with one object)
    * reduces the type checking needed on values by clients
    * also note `type` required

.pull-left.v211[``` json
"logo" : {
  "@id": "http://example.org/image-service/logo/full/200,/0/default.png",
  "service": {
    "@context": "http://iiif.io/api/image/2/context.json",
    "@id": "http://example.org/image-service/logo",
   "profile": "http://iiif.io/api/image/2/level2.json"
  }
},
```]

.pull-right.v30[
``` json
"logo": [ {
    "id": "https://example.org/image-service/logo/square/200,200/0/default.png",
    "type": "Image",
    "service": [
      {
        "id": "https://example.org/image-service/logo",
        "type": "ImageService3",
        "profile": "level2"
      }
    ]
} ],
```]

.refs[(issue [#1131](https://github.com/IIIF/api/issues/1131))]

---

## Breaking: Require `type` for all resources, with new values

* 3.0: `type` required on all resources
    * single value
    * must be used on all content resources and services

This serves several purposes, including facilitating object mapping code libraries, and forcing the serialization to generate a JSON object for the resource, not just a string with the resource's URI. The values for `type` have been changed to version-specific strings that avoid the namespace structure, for example from `iiif:Image` in 2.1 to `ImageService3` in 3.0.

(Will still see `@type` property — with `@` — when referring to object from older specifications such as the Authentication API 1.0.)

---

## Breaking: Change the `profile` property to take one compliance level

.v211[
```
"profile" : [                                       **A MESS**
  "http://iiif.io/api/image/2/level2.json",
  {
    "supports" : [ "canonicalLinkHeader", "rotationArbitrary" ]
  }
],
```]

* 3.0: `profile` has single value, the compliance level string
    * additional features described in new `extraFeatures` property
    * works with JSON-LD framing

.v30[
``` json
"profile": "level2",
"extraFeatures": [ "canonicalLinkHeader", "rotationArbitrary" ],
```]

.refs[(issues [#1275](https://github.com/IIIF/api/issues/1275), [#1373](https://github.com/IIIF/api/issues/1373), [#1554](https://github.com/IIIF/api/issues/1554), and [#1013](https://github.com/IIIF/api/issues/1013))]

---

## Breaking: Change the `service` property value to an array of objects

* 2.1.1: `service` could be a single value or an array of objects
  * 3.0: MUST be an array of objects

.pull-left.v211[
``` json
"service": {
  "id": "https://example.org/service/example",
  "profile": "https://example.org/docs/example-service.html"
}
```]

.pull-right.v30[
``` json
"service": [
  {
    "id": "https://example.org/service/example",
    "type": "Service",
    "profile": "https://example.org/docs/example-service.html"
  }
]
```]

.refs[(issue [#1131](https://github.com/IIIF/api/issues/1131))]

---

## Breaking: Remove feature names `sizeByWhListed` and `sizeByForcedWh`

* in 2.x
    * `sizeByForcedWh` inconsistently defined
    * `sizeByWhListed` implied by listing sizes so not required
    * [deprecation warning in 2.1.1](http://iiif.io/api/image/2.1/#dep-sizes)
  * 3.0 ... gone.

.refs[(pr [#727](https://github.com/IIIF/api/pull/727))]

---

## Breaking: Remove feature name `sizeByDistortedWh`

* no uesful meaning separate from `sizeByWh`
  * the question of what "non-distorting" means is arguable because all but a few special scalings intorduce some distortion as a result of rounding to integer width and height

.refs[(issue [#879](https://github.com/IIIF/api/issues/879))]

---

## Breaking: Require support for region `square` at `level1` and `level2` compliance

* region `square` introduced in 2.1
  * support now required at `level1` and `level2` compliance

.refs[(issue [#501](https://github.com/IIIF/api/issues/501))]

---

## Breaking: No longer require support for `pct:x` size at `level1` compliance

* `pct:x` size form is no longer required at `level1` compliance
  * consistent with the `pct:x,y,w,h` for region as both now `level2` features

.refs[(issue [#478](https://github.com/IIIF/api/issues/478))]

---

## Breaking: Use JSON-LD 1.1

* JSON-LD remains serialization format
  * features of the JSON-LD Community Group specification make significant improvements to the Presentation API's structure and consistency
  * also adopt for Image API (see `requiredStatement`)
  * not yet a W3C Technical Recommendation, but chances very good

.refs[(issue [#1192](https://github.com/IIIF/api/issues/1192))]

---
class: middle

# Non-Breaking Changes

Changes that are backwards compatible with version 2.1.1

---

## Extension mechanisms and registry

* New [Extensions](http://iiif.io/api/image/3.0/#48-extensions) section describes mechanisms for extension of image requests
  * New [Extra Functionality](http://iiif.io/api/image/3.0/#56-extra-functionality) section describes how extensions are described in the image information response
  * `extraQualities` and `extraFormats` properties added for description
  * (`extraFeatures` already mentioned)

* New [registry of known extensions](http://iiif.io/api/annex/registry/)
to the IIIF specifications
    * includes a [registry of Image API extensions](http://iiif.io/api/annex/registry/image-extensions/)
    * extensions intended for community use should be registered
    * (currently empty)

.refs[(issues [#1374](https://github.com/IIIF/api/issues/1374), [#1373](https://github.com/IIIF/api/issues/1373), and [#1435](https://github.com/IIIF/api/issues/1435))]

---

## Add `partOf` and `seeAlso` linking properties

Added 2 linking properties from Presentation API:

* `seeAlso` to provide a link to technical metadata
  * `partOf` supports discovery of a containing Manifest

.pull-left.v30[
``` json
"seeAlso": [
  {
    "id": "https://ex.org/image1.xml",
    "label": { "en": [ "Tech img metadata" ] },
    "type": "Dataset",
    "format": "text/xml",
    "profile": "https://ex.org/profiles/imgdata"
  }
]
```]

.pull-right.v30[
``` json
"partOf": [
  {
    "id": "https://example.org/manifest/1",
    "type": "Manifest",
    "label": { "en": [ "A Book" ] }
  }
]
```]

.refs[(issue [#1507](https://github.com/IIIF/api/issues/1507) and [#600](https://github.com/IIIF/api/issues/600))]

---

## Define JSON-LD profile for media type

A specific media-type, to be used with the HTTP headers `Accept` and `Content-Type` was defined. This media type is the JSON-LD media type, with the context in the `profile` parameter, following established conventions.

.v30[
``` json
Content-Type: application/ld+json;profile="http://iiif.io/api/image/3/context.json"
```
]

.refs[(issue [#1066](https://github.com/IIIF/api/issues/1066))]

---
class: middle

# Editorial Changes

Do not change the Image API behavior from version 2.1.1

---

## Clarify image language

[Terminology](image30-terminology) section now defines:

* **underlying image content** -- refers to the source image data. No assumptions are made about its format or structure
  * **full image** -- refers to the entire area of the underlying image content, with the pixel dimensions given in the image information document, and which is imagined as the starting point for image requests

which are used to describe the image manipulations along with:

* **extracted region** -- image obtained after the region parameter processing step (the full image if `full` used)
  * **image returned** -- image datastream returned in in response to a image request (after all manipulations)

.refs[(issue [#1425](https://github.com/IIIF/api/issues/1425))]

---

## Clarify description of the _`!w,h`_ for size

Description of the _`!w,h`_ form for the size parameter has been clarified to point out that the returned image must be as large as possible to fit within the _`w,h`_ box subject to constraints of extracted region size and server-imposed limits.

* neither width nor height of returned image larger than _`w`_ nor _`h`_ respectively
  * will not scale up size of extracted region
  * will not exceed `max` size based on server limits

.refs[(issue [#1372](https://github.com/IIIF/api/issues/1372))]

---

## Clarify that the `color` format might still yield a non-color image

Format value `color` ==> request for the resulting image with all of its color information.

``` bash
http://example.org/img123/full/max/0/color.jpg
```

If the underlying image content has no color information then the resulting image will not have any either, even with the `color` format value.

.refs[(issue [#1375](https://github.com/IIIF/api/issues/1375) and [#1435](https://github.com/IIIF/api/issues/1435))]

---

## Change examples to use `https` URIs

* Everyone should use `https`
  * So we do in order to reflect best practices for interoperable implementations

.refs[(issue [#1421](https://github.com/IIIF/api/issues/1421))]

---

## Clarify discussion of floating point representation

* discussion of floating point moved to [Canonical URI Syntax](http://iiif.io/api/image/3.0/#47-canonical-uri-syntax) section, and expanded
  * advice on using at most 10 decimal digits removed
  * clarify `pct:` values may be floating point or integer

> Size and region parameters given as percentages and the rotation parameter allow positive floating point number values. Integer values SHOULD be used where possible. When floating point values are used, they MUST consist only of decimal digits and “.” (e.g. 0.9 not +0.9), SHOULD be represented with a leading 0 if less than 1 (e.g. 0.9 not .9), and SHOULD NOT include trailing zeros (e.g. 0.9 not 0.90). Intermediate calculations may use floating point numbers and the rounding method is implementation specific.

.refs[(issue [#1468](https://github.com/IIIF/api/issues/1468) and [#1240](https://github.com/IIIF/api/issues/1240))]

---

## Clarify support for CORS

Discussion of CORS has be moved to a new [CORS](http://iiif.io/api/image/3.0/#71-cors) section and the wording clarified to make it clear that not only the `Access-Control-Allow-Origin` header but also the preflight request pattern (ie. including the `OPTIONS` header) should be supported.

> Servers should support reuse of Image API resources by following the relevant requirements of the CORS specification, including the `Access-Control-Allow-Origin` header and the preflight request pattern. A recipe for enabling these behaviors is provided in the Apache HTTP Server Implementation Notes.

.refs[(issue [#1274](https://github.com/IIIF/api/issues/1274))]

---

## Clarify `@context` may be a URI or array of URIs

2.1.1 mentioned only the Image API JSON-LD context. Description changed to make it clear that the value of `@context` may be either a single URI, or an array with extension context URIs followed by the Image API context URI.

.v30[

``` json
{
  "@context": "http://iiif.io/api/image/3/context.json",
```]

.v30[
``` json
{
  "@context": [
    "http://example.org/extension/context1.json",
    "http://iiif.io/api/image/3/context.json"
  ],
```]

.refs[(issue [#1472](https://github.com/IIIF/api/issues/1472))]

---

## Clarify that a compliance `Link` header may be returned with both Image and Image Information responses

The [description of compliance](http://iiif.io/api/image/3.0/compliance/) has been changed to note that the compliance level may be given in a HTTP `Link` header on both Image and Image Information responses.

.v30[
``` json
Link: <http://iiif.io/api/image/3/level1.json>;rel="profile"
```
]

.refs[(issue [#1365](https://github.com/IIIF/api/issues/1365))]

---

## Move implementation notes to a separate document

* New [Image API 3.0 Implementation Notes](http://iiif.io/api/image/3.0/implementation/) document was created by extracting notes from the appendices of the previous version
  * Added algorithm for handling implementation constraints on maximum sizes with `maxWidth`, `maxHeight` and/or `maxArea`
  * No [RFC 2119](https://tools.ietf.org/html/rfc2119) keywords as the implementation notes are not normative

.refs[(issues [#928](https://github.com/IIIF/api/issues/928) and [#1427](https://github.com/IIIF/api/issues/1427))]

---

## Describe implementation with static web resources

Added note about `level0` implementation with pre-generated files, and details in [Image API Compliance](http://iiif.io/api/image/3.0/compliance/#5-level-0-compliance) on interpretation of `scaleFactors`, `tiles` and `sizes` information at `level0`.

> A level 0 compliant image server MAY specify `scaleFactors` and/or `width` and `height` values for `tiles` in the Image Information response. At level 0 compliance, a service is only required to deliver images of sizes computed using the scaling factors declared in the Image Information response. If specified they should be interpreted with the following special meanings:
> 
>   * `scaleFactors` - only the specified scaling factors are supported
>   * `width`, `height` within `tiles` - clients should request only regions that correspond to output tiles of the specified dimensions
> 
> A level 0 compliant image server MAY specify `sizes` to indicate specific `width` and `height` values for sizes available for the `full` region.

.refs[(issues [#1231](https://github.com/IIIF/api/issues/1231) and [#1274](https://github.com/IIIF/api/issues/1254))]

---

## Add note encouraging adoption of HTTP/2

* New [HTTP Versions](http://iiif.io/api/image/3.0/#74-http-versions) section was added to describe issues with many concurrent requests and recommends support for HTTP/2.

.refs[(issue [#957](https://github.com/IIIF/api/issues/957))]

## Improve font and style consistency

* Use of `code` font and capitalization was made consistent for class names, property names and values when used in prose.

---
class: center, middle

# That's all folks!