Creating Collections of both Manifests and Content State Annotations

[mixterj]

CONTENTdm has a use case for allowing users to create 'favorite lists' of items in CONTENTdm collections. Sometimes these items are single image things which have their own Manifests but sometimes a user wants to 'bookmark' a specific part of an item, like a page of a book or image in a connected sequence of images.

For the first scenario we can just create a IIIF Collection Manifest and add the item Manifest to it but for the second scenario we were planning on using the Content State API to flag the specific Canvas that user wanted to bookmark.

The issue is that we can not add 'Annotation' to the Collection Manifest per this rule:

"A Collection must have the items property. Each item must be either a Collection or a Manifest. Clients must process items on a Collection."

And we do not want to create artificial Manifests due to the overhead of then supporting a persistent URI per this rule:

"The identifier in id must be able to be dereferenced to retrieve the JSON description of the Manifest, and thus must use the HTTP(S) URI scheme."

@azaroth42 suggested just using Content State and then publishing a Web Annotations AnnotationsCollection object but that would not work in any of the viewers (as of now) and seems a bit odd since the IIIF Presentation API has a mechanism for doing this but can not accommodate this specific issue. It was also suggested that we could just put all of the 'favorite items' in the AnnotationsCollection using Content State Annotations (they would be super simple for entire Manifests) but then we are in a situation where the IIIF Spec has 2 ways of essentially doing the same thing.

[azaroth42]

Discussion on call 2019-01-08 - Agreement that content state is more appropriate solution for favorite lists than collections, as favorites are pointers to things rather than the things themselves. Bookmarking is known annotation motivation, and this seems a lot like that ... and is the technology for content state. Collections can't have canvases or parts of canvases, but bookmarks of these are important. A collection viewer could be adapted to instead traverse a list of content-state annotations instead of collections and manifests and produce a similar interface.

[aisaac]

+1 Actually this sounds like a case for which our old title "import to viewers" sounds quite appropriate :-)

[azaroth42]

This sounds like an editorial issue to add "favorites list" as a use case to the docs.

[azaroth42]

Technical answer exists. Should discuss the use case in the main technical call, about overlap with Presentation API. Question as to whether Presentation API Collections should allow the inclusion of Content States, and/or whether clients should process annotation collections of content states in a similar way to Collections.

[aisaac]

Discussed in TSG call June 10 and Sept 2 and Nov 11

[azaroth42]

Action needed - document the decision in the spec.

[tomcrane]

My fault for leaving it so long, but what is the decision to document?

---

June 2020 Notes:

Tom: a manifest can be expressed as a content state json string. Would this lead to abstract arbitrary “manifests” which only exist as the favorite list. Is this the way to do it? Could it be an annotation list?
Jeff: Not yet, because no viewer supports annotation lists doing this.
Rob: pass this back to the main technical call as it cuts across several specs.
Jeff: Annotation collections works in general. What else are collection manifests for?
Several other uses of collection manifests were then given.
Rob: content state could be allowed within collection manifests at, say, 3.1 as this wouldn’t break Presentation 3.0 on the understanding that it could be ignored by browsers when not relevant.
Decision: defer as this needs broader discussion.

Sept 2020 Notes

Rob: I don't think there's a technical pain here. The pain is that in the past we've used collections and now this changes
Matt: Bookmarking annotation in a system that then converts to favorite list collections. Could more easily convert to content state annotations.
Rob: Where to document the answer? I would be happy with a recipe.
Antoine: Good to have a pointer to the recipe.
Rob: More general question -- same issue for other specs too :)

Tom: Annotated spec that links the spec and cookbook together?
Simeon: Don't see a problem with that. Imagining that for the python example in content state … could link to recipes for other languages
Tom: So not changing the normative text, but annotating that markup to read on the IIIF site to read with links to recipes without continuously churning the spec.
All: :thinking-face:
Simeon: A bit of maintenance issue and some minor technical things. Need to import blessed annotations to blessed recipes.
Tom: Not disrupting the spec or creating new versions, just useful pointers.
Antoine: For 3.2 where you refer to recipes? These like the idea of a recipe?
Tom: They don't exist …. 3.2 is still pretty drafty and informal. Should be an illustrative list of links for exporting state, but there's nothing that should go in the spec directly.
Antoine: Collection would also be such an illustration.
Tom: Yes, that definitely needs fleshing out.
Rob: Leave open and mark as editorial action needed

---

Options:

1. Purely a recipe; show how a set of content states is just a regular annotation page, nothing new required, content state spec can mention the use case but cookbook entry fleshes it out with practical advice.
2. Presentation 3.1, which must follow or coincide with Content State 1.0, permits content state annotations in Collection items. This needs an issue raised in /api and further discussion.

(I can do 2, just unsure whether it is still on the table).

[tomcrane]

Consensus is that option 1 is the answer; needs a use case note in spec but not Presentation 3.1 or normative changes.

Action - add a note about this to the spec
Action - raise an issue in Cookbook repo.

[tomcrane]

Action allocations:

@tomcrane - add note to spec
@mixterj - organise working on cookbook recipe

[azaroth42]

Done? @tomcrane @mixterj ?

[tomcrane]

1. is not done.

Wondering how to present it. People might come to the content state spec looking for a description of how to do this, but as established above, the mechanism is pure W3C annos - and the annos are more likely to have bookmarking motivations anyway.

An annotation is only a content state if it has the motivation contentState, which signifies "I am here to help you move presentation state between software contexts without an opinion on why that state exists" - but it doesn't make much difference to a client or "content state processor" what the motivation of the annos is. If a viewer has implemented content state then it can use the same mechanism to jump to a bookmark.

So I propose a new section 5.5 (coming after https://iiif.io/api/content-state/1.0/#54-search-results)

Something like:

---

5.5. Collections of Content States

As content states are regular W3C Web Annotations, the mechanism for collecting them is the same as for any W3C Annotation - the AnnotationPage:

(example that shows some annos with both `contentState` and `bookmarking` motivations)

For further discussion and use cases for collections of content states and other annotations, see the Cookbook