Annotation compliance with IIIF Presentation API and JSON-LD

[yuricus]

Short version

Annotation document generated with Mirador does not comply with JSON-LD and IIIF Presentation API 2.0, this may affect annotation endpoint implementations as well. I suggest following the standard but it may be painful in terms of changes it might entail.

Long version

IIIF Presentation API uses JSON-LD as data format. JSON-LD is the way to represent RDF data structures. To simplify interoperation with non-RDF-aware sources, IIIF Presentation API uses 'framed' JSON-LD documents, consumer or producer of those documents does not need to know about RDF data triples. In JSON-LD documents there is a @context which specifies translation of JSON fields to RDF Linked Data entities.

When Mirador produces JSON-LD for annotations, it creates incorrect JSON-LD documents, those documents do not correspond to specified @context.

Specifically, the error is in specifying original canvas annotation refers to. Mirador uses 'source' field for that. There's no 'source' field mentioned in IIIF Presentation @context, but there is 'full' field which is mapped onto “oa:hasSource” property.

I mentioned in #748 that this affects ongoing annotation work, but this problem persisted for a long time. Unfortunately, this also affects annotation endpoint. Like, for SimpleASEndpoint there's a code:

https://github.com/glenrobson/SimpleAnnotationServer/blob/master/src/main/java/uk/org/llgc/annotation/store/AnnotationUtils.java, lines 97-101

// Fix Mirador bug (rename source to full): 
Map<String, Object> tOn = (Map<String, Object>)tRoot.get("on"); 
Object tSource = tOn.get("source"); 
tOn.remove("source");
tOn.put("full", tSource); 

That also affects Catch endpoint, as far as I understand.

In ResearchSpace we store data as RDF triples natively, so compliance with JSON-LD specification is important for us.

I understand that changing this to comply with the standard may cause incompatibility between Mirador and annotation endpoints, and, in the worst case, this goes down to data storage as well.

However, I encourage to apply the change to comply with the standard.

[sdellis]

@yuricus, I just want to make sure it's understood that you are requesting the property name be changed from "source" to "full", along with updates to the relevant annotation servers to handle it?

@rsinghal is this something you could look at when you start the "LocalStorage as an annotation fallback" work (couldn't find a issue for that)?

[yuricus]

@sdellis I wasn't clear of what i'm proposing. Indeed, the change of property name from 'source' to 'full'.

[rsinghal]

We should definitely be spec compliant. I believe I structured the OA using emails from @azaroth42 , so it would be best for him to weigh in before we determine the best way to make these fixes in the code. For CATCH, I think the only change will be in the conversion between the CATCH model (which does not natively use OA) and OA in catchEndpoint.js.

This is the comment from #748, for more information:

There's a problem with json-ld generated by this component:

{ "@context": "http://iiif.io/api/presentation/2/context.json", "@type": "oa:Annotation", "motivation": [ "oa:commenting" ], "resource": [ { "@type": "dctypes:Text", "format": "text/html", "chars": "

a polygon

" } ], "on": { "@type": "oa:SpecificResource", "source": "http://oculus-dev.harvardx.harvard.edu/manifests/huam:165773/canvas/canvas-17810920.json", "selector": { "@type": "oa:SvgSelector", "value": "" }, "scope": { "@context": "http://www.harvard.edu/catch/oa.json", "@type": "catch:Viewport", "value": "xywh=-1018,0,3830,2450" } } }

in '"source": "http://oculus-dev.harvardx.harvard.edu/manifests/huam:165773/canvas/canvas-17810920.json"' there's no "source" attribute in specified json-ld context http://iiif.io/api/presentation/2/context.json, you should use "full" instead to produce json-ld that conforms to Open Annotation model.

See examples on oa:SpecificResource at http://iiif.io/api/presentation/2.0/#non-rectangular-segments.

[azaroth42]

:+1: to using "full" (from the IIIF context) not "source" (from the OA context).

Note that when the Annotation Working Group completes the updates to the model, vocabulary and protocol, IIIF is likely to adopt them directly in version 3.0 of the Presentation API.

References:

• https://github.com/IIIF/iiif.io/issues/496
• http://w3c.github.io/web-annotation/model/wd2/
• http://w3c.github.io/web-annotation/vocab/wd/
• http://w3c.github.io/web-annotation/protocol/wd/

[rsinghal]

I think it makes sense to make the necessary fix. @glenrobson, this will have an impact on your annotation store as well. @yuricus, can you submit a PR for this? I can make the necessary changes to catchEndpoint.js, if you prefer.

[glenrobson]

Happy to make the change in the SimpleAnnotationServer. I think this issue is a duplicate of #551.

[yuricus]

@glenrobson I agree it's a duplicate.

[glenrobson]

For info I've made the change in SAS from source to full.

Cheers

Glen