Mirador 4.0.0 hides supplementing annotations from the Annotations panel — a `filteredMotivations` gotcha
This article is co-authored with generative AI. While I have cross-checked facts against official documentation where possible, errors may remain. Please verify primary sources before making important decisions. TL;DR I shipped per-canvas OCR text as IIIF Presentation 3 annotations with motivation: "supplementing". Annona and other spec-aware viewers rendered them. Mirador 4.0.0 (projectmirador.org/embed) showed nothing in the Annotations side panel. Root cause: in Mirador 4.0.0 release, config.annotations.filteredMotivations defaults to ['oa:commenting', 'oa:tagging', 'sc:painting', 'commenting', 'tagging'] — supplementing is not in the allowlist, so an annotation whose only motivation is supplementing is filtered out of the side panel. Mirador master has since flipped the default to filteredMotivations: [] (no filter), but at the time of writing no release ships that change. The released filter still applies in the wild. Putting motivation as ["commenting", "supplementing"] lets the annotation through Mirador 4.0.0’s filter via commenting, while keeping supplementing so spec-aware viewers / text-overlay plugins still recognise it as a transcription. IIIF Presentation 3 §3.5 “Values for motivation” only defines painting and supplementing; other motivation terms (commenting, tagging, …) come from the Web Annotation Data Model. The basis for allowing arrays is IIIF §4.3 (Properties with Multiple Values) plus Web Annotation §3.3.5. Don’t add painting alongside. Each canvas already has a painting annotation for the image — adding another forces the viewer to pick which one “fills” the canvas, with implementation-dependent results. What happened While extending the public API for the Hiraga Yuzuru Digital Archive, I added a per-canvas OCR-text endpoint that returns annotations as a Presentation 3 AnnotationPage, referenced from each canvas’s annotations[]: ...