Recipe #0306: Linking external Annotations targeting a Canvas to a Manifest

glenrobson commented 1 year ago

Links

Original Issue: https://github.com/IIIF/cookbook-recipes/issues/306
Pull Request: https://github.com/IIIF/cookbook-recipes/pull/388
Preview: https://preview.iiif.io/cookbook/0306-linking-annotations-to-manifests/recipe/0306-linking-annotations-to-manifests/

Background and Summary

Often when working with Annotations you want to show the image that is annotated. Usually IIIF annotations target a region of a canvas but in the majority of case the canvas doesn't resolve. This recipe shows how to encode a link back to the Manifest that contains the canvas so that the image being annotated can be shown by following the partOf link to the Manifest and then searching through the Manifest for the canvas ID.

This method of linking annotations to their manifests is already implemented in a number of viewers but this recipe now documents this process.

Voting and changes

We welcome comments on the recipe and as well as voting +1, confused face or -1 feel free to add comments to this issue. If this issue is approved then the author will take account of the comments before we merge the branch in to the master cookbook branch.

If the recipe is rejected by the TRC then we will make the changes requested and resubmit it to a future TRC meeting. If you feel that your comments are substantial enough that the recipe should be looked at again by the TRC after the changes have been made please vote -1 (thumbs down). A confused face is treated as abstaining.

Changes to the recipe will only be made after the TRC voting process has concluded.

nfreire commented 1 year ago

I believe that using isPartOf may not be the best approach for modeling this kind of cases. The Web Annotation Model defines the property "scope" (oa:hasScope). https://www.w3.org/TR/annotation-model/#scope-of-a-resource It is defined as "The relationship between a Specific Resource and the resource that provides the scope or context for it in this Annotation." In my opinion, the manifest should be referenced in the "scope" property, as follows:

"target": {
        "type": "SpecificResource",
        "source": {
          "id": "https://preview.iiif.io/cookbook/0306-linking-annotations-to-manifests/recipe/0306-linking-annotations-to-manifests/canvas-1",
          "type": "Canvas",
        },
        "scope" : "https://preview.iiif.io/cookbook/0306-linking-annotations-to-manifests/recipe/0306-linking-annotations-to-manifests/annotationpage.json",
        "selector": {
          "type": "FragmentSelector",
          "conformsTo": "http://www.w3.org/TR/media-frags/",
          "value": "xywh=300,800,1200,1200"
        }
      }

giacomomarchioro commented 1 year ago

That's a good point @nfreire, thanks a lot for your comment. That would make perfect sense what makes partOf very attractive is that we can specify the type of element that the resource is part of e.g. Manifest:

          "partOf": [
            {
              "id": "https://preview.iiif.io/cookbook/0306-linking-annotations-to-manifests/recipe/0306-linking-annotations-to-manifests/annotationpage.json",
              "type": "Manifest"
            }
          ]

For a viewer, I think it could be very handy to have this because potentially an annotation could be part of many elements. And the "scope" is in fact "a resource that provides the scope" so it could be also a URL that a viewer can not consume. I don't think we can specify a type for the scope, at least I don't see any mention of it in the Web Annotation Data Model. Just to clarify: I used the definition of partOf of IIIF spec but in fact, in the web annotation data model partOf describes a relationship between the Page and the Annotation Collection but this is defined at the level of the Annotation Page, not at the Annotation. I think however we should ask for advice from @azaroth42.

nfreire commented 1 year ago

Ok, I see the importance for the use case in having type of element that the resource is part of. The scope of the annotation is a resource, so one can add an rdf:type or other properties if necessary.

But the solution with dcterms:isPartOf looks valid to me as well. I don't think that there is any problem in using dcterms:isPartOf as an attribute of the source resource. The Web Annotation Model defines how the property should be used between Pages and Collections, but this does not restrict its use in other resources.

In general, my opinion is that both solutions are valid. In Europeana, we have a similar use case and we have chosen to use scope, so maybe my opinion is biased towards using scope :)

I hope we get more feedback from others experienced with Web Annotation.

azaroth42 commented 1 year ago

Both are valid -- the web annotation model says that you can have a scope for a specific resource, and IIIF says that you can use partOf to assert that a resource is part of another resource. So the question comes down to best practice and consistency, rather than which is right or wrong.

My view is that partOf will be more consistent with other constructions, as it doesn't require the use of a SpecificResource. For example, if the annotation was instead targeting the entire canvas rather than a part of it, the annotation could have a target of the Canvas directly which is then partOf the manifest. Using scope would require a SpecificResource without a Selector which is more complicated for the simple case.

So I'm in favor of the recipe as it stands

giacomomarchioro commented 1 year ago

Thanks a lot Nuno and Robert let me know if you think I should add some additional text to clarify.

glenrobson commented 1 year ago

We were just discussing this in the cookbook authors meeting and came up with a couple of JSON-LD questions that we don't think impact the recipe but:

IIIF defines partOf as dcterms:partOf but the Web annotation data model defines it as as:partOf part of the activity streams standard. IIIF Context and Web Annotations Context.

Will the use of partOf within the canvas conflict with the Web annotations use of partOf. We think not as the IIIF context looks like it overrides the annotations use but just wanted to check.

Secondly we saw that IIIF defines partOf as dcterms:partOf but we couldn't find partOf in the list of dcterms: https://www.dublincore.org/specifications/dublin-core/dcmi-terms/ but there is isPartOf. Shoud the IIIF context point to this one? Actually it looks like there is already an issue for this.

regisrob commented 1 year ago

However, the target of the Annotation contained in the Annotation Page file will be a Specific Resource this allows us to use a partOf attribute inside the source element to point at the original Manifest containing the Canvas.

In this sentence, I feel like this allows us... should rather be , which allows us... ? Or even be another sentence... 🤷‍♂️

glenrobson commented 1 year ago

Issue 111 (Recipe #0306: Linking external Annotations targeting a Canvas to a Manifest )

+1: 16 [akrishnan15 azaroth42 digitaldogsbody dlpierce emilyewahl glenrobson jtweed julsraemy ksclarke markpbaggett mikeapp nfreire regisrob robcast thehabes tpendragon] 0: 0 [] -1: 0 [] Not TRC: 0 [] Ineligible: 1 [ioanrichards]

Result: 16 / 16 = 1.00

Super majority is in favor, issue is approved

IIIF / trc