Annotation Server

Increasingly information about resources — digital objects that might incorporate images, audio, video — or associations between resources are represented as annotations on those resources. Annotations are a powerful and flexible way of adding rich description, structure, and relationships about and between content. Commenting, tagging, transcribing, linking, classifying are all operations that can be effectively modelled as annotations.

The DLCS incorporates a state-of-the-art annotation server that can store W3C and Open Annotation web annotations, receive those annotations via the W3C Web Annotation protocol, and push those annotations to a search service for indexing.

Benefits of the DLCS Annotation Server

The DLCs Annotation Server (Elucidate) is fully standards compatible:

  1. data model: supports both the Open Annotation and W3C data models, for maximum compatibility with client applications, and future-proofing.
  2. protocol: supports the W3C Web Annotation protocol for compatibility with IIIF clients (via an appropriate javascript client library), and for other clients (such as hypothes.is) which have pledged future compliance with the W3C specification.

Elucidate interconnects seamlessly with other applications in the DLCS platform so annotations created on DLCS content can be used to drive search and discovery, or be part of the viewing experience for objects.

The use of a W3C compliant annotation server provides part of the core functionality that can be used for crowd-sourcing content classification, transcription, or description.

Technical Overview

The DLCS Annotation Server (Elucidate) exposes a REST API which supports the W3C Web Annotation protocol and complies with the W3C Web Annotation and Open Annotation (OA) data model. It is built using the Java programming language using Spring to facilitate the core web application features.

To service both the W3C and OA specifications, the REST APIs are exposed under two separate paths:

/w3c/…

/oa/…

Both paths expose the same functionality, however will exercise the different specification specific rules, conversions and contexts depending on which is used.

Annotations which are stored by and published from the server are persisted using PostgreSQL, which allows (through usage of the ‘jsonb’ database) storage and querying of JSON data whilst being able to retain relational data in order to persist associated metadata. To allow the API to be as flexible as possible so as to accommodate as many different clients as possible, annotations are persisted in the “expanded” JSON-LD state, free of any specific context. This allows clients to provide their own context, which the API will accommodate and apply to requested Annotations.

 An additional feature is the ability to “publish” Create, Read, Update, and Delete (CRUD) operations to interested third party services. Currently, this functionality is being utilised to notify an AWS SQS queue in order for other systems (including the Search Service) to consume and work with the Annotations.

Example W3C response:

{
    "id":"https://www.example.com/annotation/w3c/ac1eba810b4929264d694c98681998b1_c/6929dd97-90c3-413d-9d85-c40455d90d2c",
    "type":"Annotation",
    "body":[
        {
            "type":"TextualBody",
            "format":"text/plain",
            "value":"the last half century"
        },
        {
            "value":"entity:DATE",
            "purpose":"tagging"
        }
    ],
    "target":{
        "type":"SpecificResource",
        "dcterms:isPartOf":"http://wellcomelibrary.org/iiif/b18036430/manifest",
        "selector":{
            "type":"FragmentSelector",
            "conformsTo":"http://www.w3.org/TR/media-frags/",
            "value":"xywh=2040,576,108,46"
        },
        "source":"http://wellcomelibrary.org/iiif/b18036430/canvas/c23"
    },
    "motivation":[
        "tagging",
        "commenting"
    ],
    "@context":"http://www.w3.org/ns/anno.jsonld"
}"

For more details see: Annotation Server (Elucidate) (Github)

Roadmap: Annotation Server Control Panel

This functionality will be further expanded upon through the Control Panel; a separate component that allows the viewing and management of Annotations, as well as the ability to bulk republish Annotations to the AWS SQS queue, for example to push annotations again to the Search Service.