'target' on 'AnnotationNormalized' is not being normalized into an Array<ContentResource>

[jbaiter]

When loading the manifest https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/manifest.json with vault and drilling down into the canvas' annotations via vault.get, the target key is not being normalized into an array as specified by the type annotations on AnnotationNormalized:

const manifest = await vault.loadManifest('https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/manifest.json');
for (const canvas of vault.get<CanvasNormalized>(manifest.items)) {
    const annos = vault.get<AnnotationPageNormalized>(canvas.items)
        .flatMap(p => vault.get<AnnotationNormalized>(p.items));
    for (const anno of annos) {
      console.dir(anno.target, { depth: null });
    }
}

Expected Output (Array<ContentResource>):

[{ id: 'https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/canvas/p1', type: ??? }]
[{ id: ''https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/canvas/p1#xywh=3949,994,1091,1232', type: ??? }]

Actual Output: (ContentResourceString?)

'https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/canvas/p1'
'https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/canvas/p1#xywh=3949,994,1091,1232'

I'm also a bit confused as to why AnnotationNormalized#target has the type Array<Reference<"ContentResource">>, shouldn't it be a union Array<Reference<"ContentResource"> | ContentResourceString>? Although that's probably more of a question for https://github.com/IIIF-Commons/presentation-3-types.

[stephenwf]

This was a sticking point, as ideally the normalization step into Vault should be reversible. To completely avoid the issue Vault/parser currently doesn't touch Annotation targets (or services).

That's good to know that the types may be wrong, I think that can be solved quite quickly. The main issue is with the media frags. Originally it ended up creating a whole bunch of junk ContentResource ids in vault.

{
  "target": "https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/canvas/p1#xywh=3949,994,1091,1232"
}

So if we were to normalize the annotation targets, we'd need to make a more drastic change to the structure. One option could be to expand within the W3C spec (and update the types to reflect)

{
  "target": [{
     "type": "SpecificResource",
     "source": {"id": "https://iiif.io/api/cookbook/recipe/0036-composition-from-multiple-images/canvas/p1", "type": "Canvas"},
     "selector": { "type": "FragmentSelector", "value": "#xywh=3949,994,1091,1232" }
  }]
}

So even simple string targets get expanded out - and then possibly "compress" on the way out back to a single value.

This would be the first case of drastically changing the structure of the IIIF on the way in, so eventually removed for now.

The code to expand does exist here: https://github.com/digirati-co-uk/react-iiif-vault/blob/a9b743693fda066d12d727603cf54da8920ea837/src/utility/expand-target.ts#L15 if that felt like the way to go.

The traversal is also available to re-enable:
https://github.com/IIIF-Commons/parser/blob/main/src/presentation-3/traverse.ts#L331-L332
https://github.com/IIIF-Commons/parser/blob/main/src/presentation-3/traverse.ts#L295-L309

Very interested to get your thoughts on this "expanded" version of the annotation target, and if that would help your use cases.

[jbaiter]

Thank you for writing up the reasoning behind the current approach!!
So my use case for the annotation targets is to basically get a mapping of image -> location on canvas, i.e. the very basic viewer use case.
In that case, I'd have to check for and parse the media fragments from the URI anyways, so the expanded version of the annotation target would save me a bit of string manipulation and would make the code probably a bit cleaner.
On the other hand, I can clearly see that this would be quite a lot of effort for a very minor increase in convenience.
My main reason for opening this issue was that I got confused by the type mismatch, I think as long as the type for the target clearly expresses that it can simply be a string (whether with or without a media fragment) I (and tsc 😅 ) would be happy 🙃

[stephenwf]

Yes, it's a bit of a tough one! I think a good candidate for Vault helpers to make it a bit easier to parse with type-safety. There is a similar issue with Range targets too, as they can contain canvases, other ranges or media-frags too.

Fix for incorrect type published in:

@iiif/[email protected]

I'll convert this to a discussion for the other half