Last week, we mentioned some of the issues we encountered while working with external IIIF servers. Many of those issues are related to not complying with the IIIF specification properly, and could have been detected using automated tools. In this article, we'll take a look at some of the available tools and how to use them on your server.
IIIF Image Validator
This is an official validator developed by the IIIF Consortium for the Image API. It supports all current versions of the API and validates rather thoroughly. It requires uploading a specific test image, as it not only tests the JSON Image Information but also the actual returned images, to test the true behavior of the server. Thanks to this, this validator can detect most, if not all, of the potential issues.
You could use the IIIF validator without the test image, but you would then have to ignore many of its reported errors, and would lose a rather important part of the validation: you would not be able to tell if your server actually serves the right images.
You can head over to the validator's homepage to get the test image and run the validation. You can also use the validator right from the command line, as it is available as a Python package.
The project page includes instructions on how to make API requests to get a JSON response and integrate it into your CI pipeline, which can be useful for server implementors.
# List the available tests
$ curl 'https://image-validator.iiif.io/list_tests'
{"baseurl_redirect": {...}, "cors": {...}, ...}
# Run the CORS test
$ curl 'https://image-validator.iiif.io/test-name?server=iiif.example.com&prefix=path%2Fto%2Fiiif&identifier=path%2Fto%2Fimage&version=2.0'
{"test": "cors", "status": "success", ...}IIIF Presentation Validator
The IIIF Consortium also provides a similar validation service for the IIIF Presentation API. Similarly to the Image API validator, you can use it from its homepage, make JSON requests, or run it locally. However, it is not available as a Python package. You can check out its GitHub repository instead.
The validation works by only parsing the manifest using iiif-prezi. This parsing step detects the most common issues, especially JSON-LD, but this does not for example check that the referenced images do exist.
# Validate a manifest from a URL
$ curl 'https://presentation-validator.iiif.io/validate?version=2.1&url=https://iiif.example.com/path/to/manifest.json'
{"okay": 1, "warnings": [], "error": "None", ...}
# Validate a manifest from a local file
$ curl -X POST -d @path/to/manifest.json 'https://presentation-validator.iiif.io/validate?version=2.1'
{"okay": 1, "warnings": [], "error": "None", ...}Tripoli
Tripoli is an unofficial validator only for the IIIF Presentation API 2.1 that's written in Python. It's available as a Python package, and you can check out its documentation on Read The Docs. While the official Presentation validator also is in Python, it is not a Python package and does not have much documentation. Tripoli, on the other hand, provides a nice API to integrate some IIIF validation into your code:
import json
from tripoli import IIIFValidator
with open('manifest.json') as f:
manifest = json.load(f)
validator = IIIFValidator()
validator.validate(manifest)
print(validator.is_valid)
validator.print_errors()
validator.print_warnings()We use Tripoli to validate the IIIF manifests that Arkindex generates inside of some unit tests, ensuring that we do not accidentally break them when we make any change.
Hyperion
Hyperion is a collection of NPM packages to help with working with the IIIF Presentation API. One of its packages is @hyperion-framework/validator, which provides a validator for version 3.0 of the IIIF Presentation API using JSON Schema. While it is completely undocumented, the source code is readable and the validation process is pretty close to Tripoli's:
import fs from 'fs';
import { Validator } from '@hyperion-framework/validator'
const manifest = JSON.parse(fs.readFileSync('manifest.json', 'utf8'));
const validator = new Validator()
if (validator.validate(manifest)) {
console.log('Valid!')
} else {
console.warn('Invalid!')
console.warn(v.validators.all.errors)
}Conclusion
This was a rather brief overview of the simplest tools you can use to test an IIIF server without having to comb through every detail of the specification. While the Presentation API validators still need some work (this part of IIIF can be pretty complex), the official Image API validator can validate your server very thoroughly.
Making sure your server appears to be valid with the Image API validator should already fix most of the issues that we mentioned in our previous post, so we encourage you to do it! On most open-source IIIF server implementations, the issues can be fixed with some configuration.
Next time, we will have a look at how we handled non-compliant IIIF Image and Presentation servers in our flagship product Arkindex.