In the past few weeks, we had a look at common issues with IIIF servers, how to detect some of them and how we work around them in Arkindex. For this last post in this IIIF non-compliance series, we will look at what the new IIIF Version 3.0 specifications could change when it comes to non-compliant servers and how clients should handle them.
IIIF 3.0 came out in June 2020, and while some server implementations such as Cantaloupe already support it, most servers are still only providing IIIF 2.1. Many IIIF servers are mostly used with viewers such as Mirador or Universal Viewer on an institution's website, instead of purely being APIs. Thus, it is in an IIIF server host's interest to wait until they can upgrade both the viewers and the server. More importantly, some might operate on a "if it's not broken, don't touch it" policy, which would block upgrades for quite a while. We did however start to get a few inquiries about IIIF 3.0 support in Arkindex.
Since there are currently so few server instances, especially for the the Presentation API, we cannot do much more than predict what is going to happen with the upgrade to IIIF 3.0 from reading the new specifications, and hope for the best. Overall, it seems that little change will occur on the Image API side, which has the most issues, but some issues of the Presentation API might get fixed.
Image API
The IIIF website helpfully provides a changelog to quickly find all the differences between versions 2.1 and 3.0.
Identifier and type
The @id and @type properties are renamed to id and type, and the type becomes mandatory, with a value of ImageService3.
This can make detecting the difference between IIIF 2 and 3 quite easy, even in the case of non-compliant servers that forget to specify they are using IIIF 3 with the @context.
Simplified profile
The profile property, which could have been either a string, an object, or an array with a string and an object and specified many important properties on the server's capabilities in IIIF version 2.1, has been split up into a profile URI and the maxWidth, maxHeight, maxArea, extraQualities, extraFormats and extraFeatures properties in version 3.0.
This makes the Image Information response simpler to parse overall and avoids mistakes. We had noticed improperly-placed maximum sizes before, so this could remove some confusion seen in the wild.
Max instead of full
The full size option has been removed, as it was defined as returning the image in its full resolution and ignoring the maximum size settings.
All known IIIF servers have always followed their maximum resolution settings when replying to full, which is what the max option was supposed to provide. max is now the only available option and is defined more consistently. This can have some significant impact as full is one of the most common requests, and might be what blocks most upgrades to IIIF 3.0.
Presentation API
Similarly to the Image API, the Presentation API has a changelog. It is denser due to this API being more complex and getting multiple new features such as audio, video, and timed content.
Properties with multiple values
Properties that could have multiple values, such as metadata, thumbnail or service, now always use arrays. This avoids some type detection code between objects and arrays, which only added to the complexity of parsing an IIIF manifest.
Internationalization
Properties that can be internationalized, such as metadata labels and values or the summary (formerly known as the description) of a manifest, are now always internationalized with a simpler format using JSON objects instead of arrays:
{
"description": {
"en": ["This is a manifest."],
"fr": ["Ceci est un manifeste."],
"none": ["Manifest"]
}
}With JSON objects always used for internationalization, and JSON arrays for multiple values, most of the complexity of dealing with those special cases is removed. Properties that can only be strings are strings, and properties that might be internationalized or might have multiple values always are. This simultaneously simplifies any existing implementation that dealt with those cases, and forces other implementations that ignored those cases to handle them properly.
Annotations
The Presentation API is the largest of the IIIF APIs due to its wrapping of Images into Canvases, structuring them into one or more Ranges in a Manifest and organizing said manifests into Collections, as well as allowing Annotations on those images. This API could have been split into multiple, for example a Structure API and an Annotation API. Instead of splitting, the Presentation API now relies on the W3C Web Annotation Data Model, making multiple features redundant, such as pagination, most of the resources definition, or layers.
While this change does reduce the scope of the Presentation API to something more manageable, the switch to this W3C standard might mean a large amount of breaking changes for all annotation servers, as well as increased complexity. Our experiments with annotations and IIIF viewers in the early days of Arkindex led us to believe that less than a third of the annotation specifications were implemented; making annotations even more complex might push all implementations back even further.
More explicit examples
IIIF specifications are generally long and boring to read, because they are specifications. They have to cater to every question and resolve any ambiguity, while simultaneously trying to provide a general understanding of the goal of the standard. The big picture is easy to lose when you are deep in the specific details of a small portion of IIIF. This boringness results in many developers merely skimming through the document, ignoring most of the sections discussing more general concepts such as JSON-LD or internationalization. This behavior has led to many issues that we found in the wild, as each section contributes something to the specification and ignoring them leads to non-compliance.
A general feeling that developers acquainted with IIIF 2.x could get when skimming through both IIIF 3.0 specifications is the greatly increased complexity. A notable difference between IIIF 2 and 3 is the increase in <pre> tags, used to mark JSON examples, and their use to cover the more complex cases. Combined with the much more explicit internationalization and handling of multiple values, reading only the code blocks can make IIIF 3 look much harder.
The reality is that those more complex situations were already there, but were not shown explicitly in practical examples. Skimming through the specification meant that developers were usually implementing the standards only from the code blocks and the occasional diagrams. The code blocks in IIIF 2 showed only simple cases, often overlooking internationalization, optionally multi-valued properties, or extensibility.
This change could make a significant difference in the way IIIF is supported, as it is now possible to implement most of it by example, using all of those code blocks, and miss many fewer cases.
Conclusion
IIIF 3.0 brings, along with numerous new features, some important changes that could lead to solving some of the issues seen in the currently existing IIIF servers. This of course depends on the community's willingness to upgrade quickly, whether it comes from the client and server implementations, or the IIIF system administrators at institutions.
However, some issues are sure to remain, as they cannot be solved merely by changing the standard. Among these are redirections when moving images, providing documentation on how to report issues with a server, and tailoring a server strictly for one viewer and leaving any other API consumers stranded. Additionally, supporting both IIIF 2 and 3 will be necessary for a long time until enough servers have migrated to allow removing IIIF 2, so a large amount of the issues we've discussed in this series will still be present for a while.
Adding IIIF 3.0 support in Arkindex has not yet been planned as the demand is too low compared to the complexity of this upgrade, but it will definitely happen in the long term. We hope that our partners and clients will soon be ready to make the move with us and help make the IIIF ecosystem better, little by little.