Research: W3C Web Annotation Data Model

W3C Web Annotation Data Model

The Web Annotation Data Model specification describes a structured model and format to enable annotations to be shared and reused across different hardware and software platforms.

The specification provides a specific JSON format for ease of creation and consumption of annotations based on the conceptual model that accommodates these use cases, and the vocabulary of terms that represents it

What is an Annotation?

An annotation is considered to be a set of connected resources, typically including a body and target, and conveys that the body is related to the target. The exact nature of this relationship changes according to the intention of the annotation, but the body is most frequently somehow "about" the target.

Terminology

Name	Description
IRI	An IRI, or Internationalized Resource Identifier, is an extension to the URI specification to allow characters from Unicode, whereas URIs must be made up of a subset of ASCII characters. There is a mapping algorithm for translating between IRIs and the equivalent encoded URI form. IRIs are defined by [rfc3987].
Resource	An item of interest that may be identified by an IRI.
Web Resource	A Resource that must be identified by an IRI, as described in the Web Architecture [webarch]. Web Resources may be dereferencable via their IRI.
External Web Resource	A Web Resource which is not part of the representation of the Annotation, such as a web page, image, or video. External Web Resources are dereferencable from their IRI.
Property	A feature of a Resource, that often has a particular data type. In the model sections, the term "Property" is used to refer to only those features which are not Relationships and instead have a literal value such as a string, integer or date. The valid values for a Property are thus any data type other than object, or an array containing members of that data type if more than one is allowed.
Relationship	In the model sections, the term "Relationship" is used to distinguish those features that refer to other Resources, either by reference to the Resource's IRI or by including a description of the Resource in the Annotation's representation. The valid values for a Relationship are: a quoted string containing an IRI, an object that has the "id" property, or an array containing either of these if more than one is allowed.
Class	Resources may be divided, conceptually, into groups called "classes"; members of a class are known as Instances of the class. Resources are associated with a particular class through typing. Classes are identified by IRIs, i.e., they are also Web Resources themselves.
Type	A special Relationship that associates an Instance of a class to the Class it belongs to.
Instance	An element of a group of Resources represented by a particular Class.

Simple Example

EXAMPLE 1: Basic Annotation Model
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno1",
  "type": "Annotation",
  "body": "http://example.org/post1",
  "target": "http://example.com/page1"
}

Complete Example

EXAMPLE 2: Entirely Contrived Example Use Case
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno38",
  "type": "Annotation",
  "motivation": "commenting",
  "creator": {
    "id": "http://example.org/user1",
    "type": "Person",
    "name": "A. Person",
    "nickname": "user1"
  },
  "created": "2015-10-13T13:00:00Z",
  "generator": {
    "id": "http://example.org/client1",
    "type": "Software",
    "name": "Code v2.1",
    "homepage": "http://example.org/homepage1"
  },
  "generated": "2015-10-14T15:13:28Z",
  "stylesheet": {
    "id": "http://example.org/stylesheet1",
    "type": "CssStylesheet"
  },
  "body": [
    {
      "type": "TextualBody",
      "purpose": "tagging",
      "value": "love"
    },
    {
      "type": "Choice",
      "items": [
        {
          "type": "TextualBody",
          "purpose": "describing",
          "value": "I really love this particular bit of text in this XML. No really.",
          "format": "text/plain",
          "language": "en",
          "creator": "http://example.org/user1"
        },
        {
          "type": "SpecificResource",
          "purpose": "describing",
          "source": {
            "id": "http://example.org/comment1",
            "type": "Audio",
            "format": "audio/mpeg",
            "language": "de",
            "creator": {
              "id": "http://example.org/user2",
              "type": "Person"
            }
          }
        }
      ]
    }
  ],
  "target": {
    "type": "SpecificResource",
    "styleClass": "mystyle",
    "source": "http://example.com/document1",
    "state": [
      {
        "type": "HttpRequestState",
        "value": "Accept: application/xml",
        "refinedBy": {
          "type": "TimeState",
          "sourceDate": "2015-09-25T12:00:00Z"
        }
      }
    ],
    "selector": {
      "type": "FragmentSelector",
      "value": "xpointer(/doc/body/section[2]/para[1])",
      "refinedBy": {
        "type": "TextPositionSelector",
        "start": 6,
        "end": 27
      }
    }
  }
}

Related Projects

• Hypothesis - Annotation of the web, with anyone, anywhere.
• Apache Annotator - Provides annotation enabling code for browsers, servers, humans.
• Open Annotation - Deprecated data model that lead to W3C WADL.