Annotation data model

Explaining the data model used for representing Annotations in the Annotations API.

The Annotations API adopted the Web Annotation Data Model as a base model for exchanging annotations between client applications and the API.

Background

The Web Annotation Data Model (or simply WA) is a W3C recommendation that describes a model and format to share annotations across different platforms.

Please note that, even though we have adopted WA as underlying data model for this API, it is not expected that we support the full extent of the model. We thus advise to look at the EDM Annotations profile which describes the basics of our implementation and, in particular, the section on Annotation Scenarios for a comprehensive list of the different kinds of annotations that we support.

Basics of the model

In WA, an annotation is essentially a reified relation between two or more resources, typically a body and a target, and conveys that the body reflects what is intended to be said about the target. A body can also be absent to describe situations where a target is simply bookmarked. A target can represent a resource or just a part of it that is being annotated.

Being reified as a class enables an annotation to be further described with a motivation which expresses the reason why the annotation was created but also some provenance information such as the user that created the annotation and the software application that was used, as well as the times when it was initially created and sent to the API.

Representation in JSON-LD

Annotation

FieldDatatypeDescription
@contextString (URL)The URL of the JSON-LD context. (always with value "http://www.w3.org/ns/anno.jsonld")
idString (URI)The identifier of the Annotation. It is automatically generated unless a local identifier is specified upon creation.
typeStringAlways has the values of "Annotation".
createdString (DateTime)The time at which the Annotation was created by the client application. It must be expressed in ISO8601 format and should have a timezone specified.
creatorObject (Agent)The agent responsible for creating the Annotation. This may be either a human or software agent.
generatedString (DateTime)The time at which the annotation was sent to the server.
generatorObject (Software)The agent responsible for generating the Annotation. Typically a client application used to create the annotation.
motivationStringExpresses the reason why the annotation was created. The value can be either "tagging" or "linking".
bodyString or Object (Semantic Resource or Textual Body)A body conveying what is intended to be said about the target. If the value is provided as a string, then it is interpreted as the URI and must only be used for the semantic tagging scenario. See the application scenarios section for more information.
bodyValueStringA string conveying the tag text. This field must only be used in combination with "tagging" as motivation and when the language of the tag is not known. Otherwise, it is recommended to use the body field as defined in the Application Scenarios section.
targetString or Array (String)The URL of the resource that is being annotated. An array of URLs may also be set (mostly used for the object linking).
viaStringThe URL of the annotation, if available in an external service.

Agent

An Agent can be either a Person or a Software. Typically the Person corresponds to the user that created the annotation while the Software reflects the client application that was used to create it. A Software can also create annotations if they result from an automatic process.

FieldDatatypeDescription
typeStringEither "Person" or "Software".
nameStringThe name of the agent. Either the name of the user that created the annotation, or the name of the client software that was used to create it.
homepageStringThe homepage of the user or client application, if available.

Semantic Resource

A Semantic Resource is used whenever an external resource needs to be referenced as the body of the annotation. It is mostly used for Semantic Tagging.

FieldDatatypeDescription
typeStringAlways "SpecificResource".
sourceString (URI)The URI of the resource being referred as body.
languageString (ISO639)The ISO639 language code corresponding to the language of the resource.

Optional and mandatory fields

FieldPOSTPUTDELETEREAD
@contextOMN/AM
idOMN/AM
typeOMN/AM
createdOMN/AM
creatorMMN/AM
generatedOMN/AM
generatorOMN/AM
motivationMMN/AM
bodyOM (either body or bodyValue)N/AM (either body or bodyValue)
bodyValueOM (either body or bodyValue)N/AM (either body or bodyValue)
targetMMN/AM

Example:

{
  "@context": “http://www.w3.org/ns/anno.jsonld”
  "id": "http://data.europeana.eu/annotations/1",
  "type": "Annotation",
  "created": "2015-03-10T14:08:07Z",
  "creator": {
    "type": "Person",
    "name": "John Smith"
  },
  "generated": "2015-04-01T09:00:00Z",
  "generator": {
      "type": "Software",
      "name": "HistoryPin",
      "homepage": "https://www.historypin.org/"
  },
  "motivation": "tagging",
  "bodyValue": "MyBeautifulTag",
  "target": "http://data.europeana.eu/item/92062/BibliographicResource_1000126189360"
}