IIIF NamedQueries should identify assets with errors

[donaldgray]

NamedQueries (NQ) don't check for the existence of an "errors" property when returning asset details for iiif-manifests, by default everything is rendered and treated the same. This can result in some images being rendered with either missing or 0 width and height values. e.g.

Failed Canvas example

{
    "id": ".../iiif-img/2/1/foo/canvas/c/2",
    "type": "Canvas",
    "label": { "en": ["Canvas 2"] },
    "thumbnail": [
        {
            "id": ".../thumbs/2/1/foo/full/0,0/0/default.jpg",
            "type": "Image",
            "format": "image/jpeg",
            "service": [
                {
                    "@context": "http://iiif.io/api/image/3/context.json",
                    "id": ".../thumbs/v3/2/1/foo",
                    "type": "ImageService3",
                    "profile": "level0",
                    "sizes": [
                        {
                            "width": 0,
                            "height": 0
                        }
                    ]
                }
            ]
        }
    ],
    "items": [
        {
            "id": ".../iiif-img/2/1/foo/canvas/c/2/page",
            "type": "AnnotationPage",
            "items": [
                {
                    "id": ".../iiif-img/2/1/foo/canvas/c/2/page/image",
                    "type": "Annotation",
                    "motivation": "painting",
                    "body": {
                        "id": ".../iiif-img/2/1/foo/full/0,0/0/default.jpg",
                        "type": "Image",
                        "format": "image/jpeg",
                        "service": [
                            {
                                "@context": "http://iiif.io/api/image/3/context.json",
                                "id": ".../iiif-img/v3/2/1/foo",
                                "type": "ImageService3",
                                "profile": "level2"
                            }
                        ]
                    },
                    "target": ".../iiif-img/2/1/foo/canvas/c/2"
                }
            ]
        }
    ]
}

To enable us to highlight failing assets in a backwards compatible manner we should introduce a new NQ configuration parameter: errorsAs. There is only 1 valid value for this, seeAlso (valid values may be expanded in the future).

errorsAs=seeAlso is a NQ IIIF projection specific value (ie ZIP or PDF projection won't handle it). If errorsAs={somethingElse} is present it is ignored.

If errorsAs=seeAlso is configured in a NQ then a "seeAlso" should be added to the relevant canvases. Note that this could be on IIIF 2.1 or 3 manifest. The output error shouldn't be the Images.Error value as it's publicly accessible so we shouldn't necessarily output full error details as it could contain origin, stack-traces etc

The standard AnnotationPage, Annotation, Image etc should still be output.

Example NQ: assetOrder=n1;n2&s1=p1&space=p2&errorsAs=seeAlso

Original ticket suggestion below horizontal line

---

What can we add to the canvas to signify that the item failed to process while ensuring it is still valid IIIF. Possible options

• Use a valid W3C Annotation with a known string value?
  • "tagging" or "classifying" annotation with known value like "error: failed to process" (note that this is a publicly accessible URL so we shouldn't necessarily output full error details as it could contain origin).
• No body but canvas has no image annotation?
  • What @id would we use?
• Something else?

[tomcrane]

A possibly simpler but slightly hand-wavy way to do it:

{
    "id": ".../iiif-img/2/1/foo/canvas/c/2",
    "type": "Canvas",
    ...
    "seeAlso": [
         {
               "id": "https://api.dlcs.io/customers/2/spaces/1/foo",
               "type": "https://dlcs.io/vocab/Image",
               "profile": "https://dlcs.io/vocab/error-indicator"
               "label": { "en": [ "This asset has an error which prevents it being fully represented in the named query" ] },
         }
    ]
}

The type and profile are fully-qualified to avoid need for any @context extras (although we could make type Dataset).

These URLs aren't quite right I need to check the correct values.

Then:

if(canvas.seeAlso != null && canvas.seeAlso.Any(x => x.profile == ERROR_PROFILE))
{
     // there's an error on this canvas, go look at it if you can access that `id`
}

[donaldgray]

Should this be an additional parameter in configured NQ? This is a change in behaviour so could affect existing usages of NQ's (you need to strip out the "seeAlso" (or whatever we use). To avoid this should the existing behaviour of outputting 0,0 errors persist unless you specify a parameter in the NQ setup. If so - what does that look like? ?highlightErrors=true ?

[donaldgray]

As discussed with @tomcrane - rather than introduce a new boolean NQ configuration parameter as suggested in the above comment we will use a new errorsAs propertyl. The only valid value for this is currently seeAlso (so errorsAs=seeAlso) but gives scope in the future to add alternative means to handle errors.

Will update original issue description to summarise discussion.