Annotation implementation & W3C standard compliance - bounswe/bounswe2019group9 GitHub Wiki

The annotation service is a critical feature in our project. After reading out and digging into the details of the W3C Annotation Model Standard, we have narrowed it down to the below scheme to use in our case with respect to our needs.

The original docs for the annotation model can be accessed from this link:

https://www.w3.org/TR/annotation-model/

Our Scheme Includes:

Term	Type	Description
@context	Property	The context that determines the meaning of the JSON as an Annotation.The Annotation MUST have 1 or more @context values and http://www.w3.org/ns/anno.jsonld MUST be one of them. If there is only one value, then it MUST be provided as a string.
id	Property	The identity of the Annotation.An Annotation MUST have exactly 1 IRI that identifies it.
type	Relationship	The type of the Annotation.An Annotation MUST have 1 or more types, and the Annotation class MUST be one of them.
Annotation	Class	The class for Web Annotations. The Annotation class MUST be associated with an Annotation using type.
body	Relationship	The relationship between an Annotation and its Body.There SHOULD be 1 or more body relationships associated with an Annotation but there MAY be 0.
target	Relationship	The relationship between an Annotation and its Target. There MUST be 1 or more target relationships associated with an Annotation.
creator	Relationship	The agent responsible for creating the resource. This may be either a human, an organization or a software agent. There SHOULD be exactly 1 creator relationship for Annotation and Body, but MAY be 0 or more than 1, as the resource's creator may wish to remain anonymous, or multiple agents may have worked together on it. The relationships MAY be associated with other resources.
created	Property	The time at which the resource was created. There SHOULD be exactly 1 created property for Annotation and Body, and MUST NOT be more than 1. The property MAY be associated with other resources. The datetime MUST be a xsd:dateTime with the UTC timezone expressed as "Z".
modified	Property	The time at which the resource was modified, after creation. There MAY be exactly 1 modified property for Annotation and Body, and MUST NOT be more than 1. The property MAY be associated with other resources. The datetime MUST be a xsd:dateTime with the UTC timezone expressed as "Z".
motivation	Relationship	The relationship between an Annotation and a Motivation. There SHOULD be exactly 1 motivation for each Annotation, and MAY be 0 or more than 1.

Motivation field is one of these:

Term	Type	Description
Motivation	Class	The Motivation for an Annotation is a reason for its creation, and might include things like Replying to another annotation, Commenting on a resource, or Linking to a related resource.
assessing	Instance	The motivation for when the user intends to assess the target resource in some way, rather than simply make a comment about it. For example to write a review or assessment of a book, assess the quality of a dataset, or provide an assessment of a student's work.
bookmarking	Instance	The motivation for when the user intends to create a bookmark to the Target or part thereof. For example an Annotation that bookmarks the point in a text where the reader finished reading.
classifying	Instance	The motivation for when the user intends to classify the Target as something. For example to classify an image as a portrait.
commenting	Instance	The motivation for when the user intends to comment about the Target. For example to provide a commentary about a particular PDF document.
describing	Instance	The motivation for when the user intends to describe the Target, as opposed to (for example) a comment about it. For example describing the above PDF's contents, rather than commenting on their accuracy.
editing	Instance	The motivation for when the user intends to request a change or edit to the Target resource. For example an Annotation that requests a typo to be corrected.
highlighting	Instance	The motivation for when the user intends to highlight the Target resource or segment of it. For example to draw attention to the selected text that the annotator disagrees with.
identifying	Instance	The motivation for when the user intends to assign an identity to the Target. For example to associate the IRI that identifies a city with a mention of the city in a web page.
linking	Instance	The motivation for when the user intends to link to a resource related to the Target.
moderating	Instance	The motivation for when the user intends to assign some value or quality to the Target. For example annotating an Annotation to moderate it up in a trust network or threaded discussion.
questioning	Instance	The motivation for when the user intends to ask a question about the Target. For example to ask for assistance with a particular section of text, or question its veracity.
replying	Instance	The motivation for when the user intends to reply to a previous statement, either an Annotation or another resource. For example providing the assistance requested in the above.
tagging	Instance	The motivation for when the user intends to associate a tag with the Target.

The creator field is as follows:

Term	Type	Description
id	Property	The IRI that identifies the agent. An Agent SHOULD have exactly 1 IRI that identifies it, and MUST NOT have more than 1.
type	Relationship	The type of the Agent. An Agent SHOULD have 1 or more classes, from those listed below.
Person	Class	The class for a human agent.
name	Property	The name of the agent. Each agent SHOULD have exactly 1 name property, and MAY have 0 or more.
email	Relationship	The email address associated with the agent, using the mailto: IRI scheme [rfc6086]. Each agent MAY have 1 or more email addresses.

Our body field is always TextualBody

Term	Type	Description
id	Property	The IRI that identifies the Textual Body. The Body MAY have exactly 1 IRI that identifies it.
type	Relationship	The type of the Textual Body resource. The Body SHOULD have the TextualBody class, and MAY have other classes.
TextualBody	Class	A class assigned to the Body for embedding textual resources within the Annotation. The Body SHOULD have the TextualBody class.
value	Property	The character sequence of the content of the Textual Body. There MUST be exactly 1 value property associated with the TextualBody.

Our target field is as follows

Term	Type	Description
id	Property	The IRI that identifies the Body or Target resource. Bodies or Targets which are External Web Resources MUST have exactly 1 id with the value of the resource's IRI.
format	Property	The format of the Web Resource's content. The Body or Target SHOULD have exactly 1 format associated with it, but MAY have 0 or more. The value of the property SHOULD be the media-type of the format, following the [rfc6838] specification.
type	Relationship	The type of the Body or Target resource. The Body or Target MAY have 1 or more types, and if so, the value SHOULD be drawn from the list of classes below, but MAY come from other vocabularies.
selector	Relationship	The relationship between a Specific Resource and a Selector. There MAY be 0 or more selector relationships associated with a Specific Resource. Multiple Selectors SHOULD select the same content, however some Selectors will not have the same precision as others. Consuming user agents MUST pick one of the described segments, if they are different.

The target type can be one of below:

Term	Type	Description
Image	Class	The class for image resources, primarily intended to be seen.
Text	Class	The class for a resource primarily intended to be read.

The selector field of the target is as follows:

Term	Type	Description
type	Relationship	The class of the Selector.FragmentSelectors MUST have exactly 1 type and the value MUST be FragmentSelector.
FragmentSelector	Class	A resource which describes the Segment through the use of the fragment component of an IRI.
value	Property	The contents of the fragment component of an IRI that describes the Segment. The FragmentSelector MUST have exactly 1 value property.
conformsTo	Relationship	The relationship between the FragmentSelector and the specification that defines the syntax of the IRI fragment in the value property. The Fragment Selector SHOULD have exactly 1 conformsTo link to the specification that defines the syntax of the fragment and MUST NOT have more than 1.

The conformsTo and value fields are as follows:

Name	Fragment Specification	Description
Plain Text	http://tools.ietf.org/rfc/rfc5147	[rfc5147] Example: char=0,10
Media	http://www.w3.org/TR/media-frags/	[media-frags] Example: xywh=50,50,640,480

So the annotation format is as below:

Image source:

  {
    "@context": "http://www.w3.org/ns/anno.jsonld",
    "id": "https://api.bounswe2019group9.tk/annotations?id=1",
    "type": "Annotation",
    "creator": {
      "id": "https://bounswe2019group9.tk/users/1",
      "name": "John Russel",
      "email": "[email protected]"
    },
    "created": "2015-01-28T12:00:00Z",
    "modified": "2015-01-29T09:00:00Z",
    "body": {
      "type" : "TextualBody",
      "value" : "Great Essay",
      "format" : "text/plain"
    },
    "motivation": "assessing",
    "target": {
      "id": "https://api.bounswe2019group9.tk/images/image1.jpg",
      "type": "Image",
      "format": "image/jpeg",
      "selector": {
        "type": "FragmentSelector",
        "conformsTo": "http://www.w3.org/TR/media-frags/",
        "value": "xywh=100,100,300,300"
      }
    }
  }

Text Source:

  {
    "@context": "http://www.w3.org/ns/anno.jsonld",
    "id": "http://api.bounswe2019group9.tk/annotation/find?id=2",
    "type": "Annotation",
    "creator": {
      "id": "https://bounswe2019group9.tk/users/1",
      "name": "John Russel",
      "email": "[email protected]"
    },
    "created": "2015-01-28T12:00:00Z",
    "modified": "2015-01-29T09:00:00Z",
    "body": {
      "type" : "TextualBody",
      "value" : "Bad Mistake",
      "format" : "text/plain"
    },
    "motivation": "commenting",
    "target": {
      "id": "https://api.bounswe2019group9.tk/essays/getSourceByEssayId?id=2",
      "type": "Text",
      "format" : "text/plain",
      "selector": {
        "type": "FragmentSelector",
        "conformsTo": "http://tools.ietf.org/rfc/rfc5147",
        "value": "char=0,10"
      }
    }
  }

Our Annotation API endpoints can be found in the API Doc Part of this document.