What is IIIF Content State?

Tom Crane
3 min readNov 29, 2020


“Have a look at this…” you might say, spinning the book round and marking the place with your finger.

IIIF Content State is how we point at things in IIIF.

Why do we want to point at things? So we can make a note for ourselves, or show someone else. This is something like a citation. A footnote tells me the relevant passage is on page 43. We can manage references in software tools like Zotero or EndNote, particularly references to things on the web. A citation is a blob of information that conforms to some accepted standard. If we understand the standard, we can find the thing it references. Sometimes software understands these standards, too.

Like citations, Content States are blobs of IIIF that point at IIIF resources, or specific parts of them, as precisely as we need. IIIF viewers and tools that understand a Content State can load the thing it points at, and then focus attention on a relevant part.

The simplest Content State is just the URL of a IIIF resource — a Manifest, the unit of distribution for digital objects in IIIF. We know how to pass URLs around, and IIIF viewers already know how to load and display them. Sometimes we need more precision: a particular image within the manifest, a part of that image, a chapter of a book, a segment of audio, a single word where a search engine has matched text and generated some results.

Content State is a way for humans to share bookmarks, and it’s also a way for search results to point at the exact part of a digital object that they match. A IIIF Discovery platform can use Content State to get from search results to views of objects.

We might want to point at more than one thing at a time. A Content State can have multiple targets, perhaps to compare similar details. I can send you a multi-object Content State, so you can see the two views I am comparing.

Can’t you do this anyway with the IIIF Presentation API and Web Annotations?

Yes. In fact, that’s really all Content State is. Content States are just Web Annotations that target IIIF resources, just as in the rest of IIIF. The Content State specification adds only one new thing to the IIIF model, a motivation contentState, so that if we find an annotation labelled with this motivation, we know what it’s for.

What’s new in the Content State specification is a description of how to pass the Content State around: how we make practical use of this idea in software. It provides a protocol: “if you want to pass a Content State on a query string, do it like this…”

It gives us mechanisms that software can implement to achieve interoperability. We already have interoperability of content with the Presentation API — using the same content in different tools and viewers, remixing, annotation and so on. Content State gives us interoperability for IIIF resources across software — how we take some view of a IIIF resource from one context to another.

How does Content State relate to the other Discovery work happening in the IIIF community?

The specification work so far is founded on two assumptions, that we hope are so fundamental that they don’t prejudge the ways humans go about Discovery. We think it’s a given that:

Any system of Discovery will need to find out what there is to discover, and keep itself up to date with those sources.

This gives us the Change Discovery API

You need a way of getting from a found thing to a viewing experience for that thing, however you found it and however you view it.

This gives us the Content State API

The Content State API has many other use cases beyond these “import to viewer” scenarios. In fact, every IIIF viewer already implements a simple form of content state. The specification formalises protocols on top of the IIIF model we already have.

The Content State API makes no assumptions about what the user experience of Content State might be. In the past, we had the drag and drop pattern for the IIIF icon. While drag and drop is one of the described protocols for a Content State to get from one place to another, the specification is silent on how a user experiences this. Those patterns don’t belong to the API.

The latest draft of the IIIF Content State API is published on the IIIF site.



Tom Crane

Technology Director, Digirati