Annotations Documentation

1. Data Model

Our annotation data model is composed of many data schemas.

1.1. Annotation Data Model Fields:

1. '@context':

• Type: String
• Required: True
• Default: http://www.w3.org/ns/anno.jsonld

2. 'type':

• Type: String
• Required: True
• Default: Annotation

3. 'body':

• Type: [BodySchema]
• Required: False

4. 'target':

• Type: [SpecificResourceSchema]
• Required: True

1.2. BodySchema Data Schema Fields:

1. 'format':

• Type: String
• Required: False

2. 'language':

• Type: String
• Required: False

3. 'textDirection':

• Type: String
• Required: False
• Value: 'rtl' || 'ltr' || 'auto'

4. 'type':

• Type: String
• Required: True

BodySchema schema is discriminated by type field into two different objects for type: 'TextualBody' and type: 'Image'

For type:'TextualBody', we have a required field 'value' of type String. For type:'Image', we have a required field 'id' of type String.

1.3. SpecificResourceSchema Data Schema Fields:

1. 'source':

• Type: String
• Required: True

2. 'selector':

• Type: RefinedSelectorSchema
• Required: True

1.4. RefinedSelectorSchema Data Schema Fields:

1. 'refinedBy':

• Type: SelectorSchema
• Required : False

RefinedSelectorSchema schema is discriminated by type field into two different objects for type: 'TextPositionSelector', type:'XPathSelector and type: 'FragmentSelector'. SelectorSchema is an empty schema which is discriminated by type to these same 3 types.

For types discriminated with type:'TextPositionSelector' we have required fields 'start' and 'end' of type Number.

For types discriminated with type:'XPathSelector' we have required field 'value' of type String.

For types discriminated with type:'FragmentSelector' we have required field 'value' of type String and required field 'conformsTo' of type String with default value "http://www.w3.org/TR/media-frags/".

2. Endpoints

2.1. POST /api/annotations This endpoint is used for creating an annotation. Request body should be in accordance with the data model explained above.

2.2. GET /api/annotations/:id This endpoint is used for reading an annotation with id=:id from the database.

2.3. GET /api/annotations This endpoint is used for getting only the annotations associated with one resouce. A query parameter 'url' is expected, it is the url of the resource we want to get the annotations of.

2.4. PUT /api/annotations/:id This endpoint is used for updating an annotation with id=:id from the database. Request body should be in accordance with the data model explained above.

2.5. DELETE /api/annotations/:id This endpoint is used for deleting an annotation with id=:di from the database.

3. Supported Annotations

3.1. Body We support annotations with no body. If there is a body, it should be an array of TextualBody objects or Image type External Web Resources. These types will be used to annotate objects with text and image respectively in our platform.

Note that even if we will not be using these in our platform, the backend annotation data model supports all External Web Resources with single or no language.

3.2. Target As targets, we only support Specific Resources.

We support Fragment Selectors, XPath Selectors and Text Position Selectors. We also let this selector be refined by one selector. This second selector can be one of the listed types.

Here are extra restrictions on how we plan to use annotations:

• There will be exactly 1 target per annotation.
• The target's IRI('source' field) will be the URL to the web page of the object the user is annotating. For an event, for example, it will be http:/..../events/:eventid
• The target's selector will be of type XPathSelector and will select the annotated part of the object(description, images, artists, location).
• The selector that refines the target's selector will be a Text Position selector or a Fragment selector that acts on text or image.