Abstract

Annotations are typically used to convey information about a resource or associations between resources. Simple examples include a comment or tag on a single web page or image, or a blog post about a news article.

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. Common use cases can be modeled in a manner that is simple and convenient, while at the same time enabling more complex requirements, including linking arbitrary content to a particular data point or to segments of timed multimedia resources.

The specification provides both a conceptual model that accommodates these use cases, and the vocabulary of terms that represents it. A specific JSON format is recommended for ease of creation and consumption of the annotations.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a work in progress. No section should be considered final, and the absence of any content does not imply that such content is out of scope, or may not appear in the future. If you feel something should be covered, please tell us!

This specification was derived from the Open Annotation Community Group's outcomes, and details of the differences between the two are maintained in the Acknowledgement appendix.

This document was published by the Web Annotation Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-annotation@w3.org (subscribe, archives). All comments are welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

Table of Contents

1. Introduction

This section is non-normative.

Annotating, the act of creating associations between distinct pieces of information, is a pervasive activity online in many guises. Web citizens make comments about online resources using either tools built in to the hosting web site, external web services, or the functionality of an annotation client. Comments about shared photos or videos, reviews of products, or even social network mentions of web resources could all be considered as annotations. In addition, there are a plethora of "sticky note" systems and stand-alone multimedia annotation systems. This specification describes a common approach to expressing these annotations, and more.

The Web Annotation Data Model provides an extensible, interoperable framework for expressing annotations such that they can easily be shared between platforms, with sufficient richness of expression to satisfy complex requirements while remaining simple enough to also allow for the most common use cases, such as attaching a piece of text to a single web resource.

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. This perspective results in a basic model with three parts, depicted below. The full model supports additional functionality, enabling content to be embedded within the annotation, selecting arbitrary segments of resources, choosing the appropriate representation of a resource and providing styling hints to help clients render the annotation appropriately. Annotations created by or intended for machines are also possible, ensuring that the Data Web is not ignored in favor of only considering the human-oriented Document Web.

Basic Annotation Model

The Web Annotation Data Model does not prescribe a transport protocol for creating, managing and retrieving annotations. Instead it describes a resource oriented structure and serialization of that structure that could be carried over many different protocols. The related [annotation-protocol] specification describes a recommended transport layer, which may be adopted separately.

1.1 Aims of the Model

The primary aim of the Web Annotation Data Model is to provide a standard description model and format to enable annotations to be shared between systems. This interoperability may be either for sharing with others, or the migration of private annotations between devices or platforms. The shared annotations must be able to be integrated into existing collections and reused without loss of significant information. The model should cover as many annotation use cases as possible, while keeping the simple annotations easy and expanding from that baseline to make complex uses possible.

The Web Annotation Data Model is a single, consistent model that can be used by all interested parties. All efforts have been made to keep the implementation costs for both producers and consumers to a minimum. A single method of fulfilling a use case is strongly preferred over multiple methods, unless there are existing standards that need to be accommodated or there is a significant cost associated with a method that is otherwise necessary.

1.2 Diagrams and Examples

The examples throughout the document are serialized as [JSON-LD] using the Context given in Appendix B, and also as [Turtle] with the prefixes taken from the namespace declarations given in Appendix A.

The diagrams use the following style

1.3 Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [rfc2119].

2. Web Annotation Principles

The Web Annotation Data Model is defined using the following basic principles:

The following principles describe additional distinctions regarding the exact nature of Target and Body:

The following principles describe additional semantics regarding multiple resources:

3. Web Annotation Framework

3.1 Annotations

An Annotation is a web resource. Typically, an Annotation has a single Body, which is a comment or other descriptive resource, and a single Target that the Body is somehow "about". The Annotation likely also has additional descriptive properties.

Example Use Case: Alice has written a post that makes a comment about a particular web page. Her client creates an Annotation with the post as the body resource, and the web page as the target resource.

Model

TermTypeURIDescription
@contextProperty - The context that determines the meaning of the JSON as an Annotation
The Annotation MUST have exactly 1 @context key and the value MUST be http://www.w3.org/ns/anno.jsonld
idProperty - The identity of the Annotation
An Annotation SHOULD have exactly 1 http/https URI that identifies it.
typeRelationshiprdf:typeThe relationship between the Annotation and its class.
An Annotation MUST have at least the Annotation class, and MAY have other classes.
AnnotationClassoa:AnnotationThe class for Web Annotations
The Annotation class MUST be associated with an Annotation using type.
bodyRelationship
Property
oa:hasBodyThe relationship between an Annotation and its Body
There SHOULD be 1 or more body relationships or properties associated with an Annotation but there MAY be 0.
Note
When the body is a relationship (it is a URI) it MUST be given as the value of an id property of an object in the JSON-LD serialization.
targetRelationshipoa:hasTargetThe relationship between an Annotation and its Target
There MUST be 1 or more target relationships associated with an Annotation.

Example

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

3.1.1 Creation Information

It is often important to have information about the context in which the Annotation was created. In particular, the person, organization or machine responsible for the Annotation deserves credit for their contribution, and the time at which the Annotation was created is useful for filtering out old, potentially irrelevant content. The creator of the Annotation is also useful for determining the trustworthiness of the Annotation. The software used to create and serialize the Annotation, along with when that activity occurred, is useful for both advertising and debugging issues.

Example Use Case: Beatrice writes a review of a restaurant online, and wishes to be associated with that review so that her friends know that it was her review and can trust it. Her client adds her account's identity, and its own identity, to the Annotation.

Model

TermTypeURIDescription
creatorRelationshipdcterms:creatorThe agent responsible for creating the Annotation. This may be either a human or software agent.
There SHOULD be exactly 1 creator relationship, but MAY be 0 or more than 1, as the Annotation's creator may wish to remain anonymous, or multiple agents may have worked together on it.
createdPropertydcterms:createdThe time at which the Annotation was created.
There SHOULD be exactly 1 created property per Annotation, and MUST NOT be more than 1. The datetime MUST be expressed in the xsd:dateTime format, and SHOULD have a timezone specified.
generatorRelationshipprov:wasGeneratedByThe agent responsible for generating the Annotation to be transferred between client and server.
There MAY be 0 or more generator relationships.
generatedPropertyprov:generatedAtTimeThe time at which the agent referenced by generator generated the Annotation, and any subsequent substantially different one.
There MAY be exactly 1 generated property per Annotation, and MUST NOT be more than 1. The datetime MUST be expressed in the xsd:dateTime format, and SHOULD have a timezone specified.

Example

Example 3: Creation Information (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno2",
  "type": "Annotation",
  "creator": "http://example.org/user1",
  "created": "2015-01-28T12:00:00Z",
  "generator": "http://example.org/client1",
  "generated": "2015-02-04T12:00:00Z",
  "body": {"id": "http://example.net/review1"},
  "target": "http://example.com/restaurant1"
}

3.1.2 Creation Agents

More information about the agents involved in the creation of an Annotation is normally required beyond a URI that identifies them. This includes whether they are an individual, a group or a piece of software and properties such as real name, account name, and email address.

Example Use Case: Corina wants to submit an Annotation to a system that does not manage her identity, and would like a pseudonym to be displayed. Her client adds this information to the Annotation to send to the service.

Model

TermTypeURIDescription
idProperty - The identity of the agent
An Agent SHOULD have exactly 1 http/https URI that identifies it.
typeRelationshiprdf:typeThe class of the Body
An Agent SHOULD have at least 1 class, from those below.
PersonClassfoaf:PersonThe class for a human agent, typically used as the class of the creator of the Annotation
OrganizationClassfoaf:OrganizationThe class for an organization, as opposed to an individual. This might be used as the class creator of the Annotation.
SoftwareClassprov:SoftwareAgentThe class for a software agent, typically used as the class of the generator of the Annotation. It might also be used for the object of the creator for machine generated Annotations.
namePropertyfoaf:nameThe name of the agent.
Each agent SHOULD have exactly 1 name property.
accountPropertyfoaf:nickThe account name of the agent.
Each agent SHOULD have exactly 1 nick property.
emailRelationshipfoaf:mboxThe email address associated with the agent, using the mailto: URI scheme.
Each agent MAY have 1 or more email addresses
homepageRelationshipfoaf:homepageThe home page for the agent.
Each agent MAY have 1 or more home pages.

Example

Example 5: Creation Agents (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno3",
  "type": "Annotation",
  "creator": {
    "id": "http://example.org/user1",
    "type": "Person",
    "name": "My Pseudonym",
    "nick": "pseudo"
  },
  "generator": {
    "id": "http://example.org/client1",
    "type": "SoftwareAgent",
    "name": "Code v2.1",
    "homepage": "http://example.org/client1/homepage1"
  },
  "body": {"id": "http://example.net/review1"},
  "target": "http://example.com/restaurant1"
}

3.1.3 Creation Reason

In many cases it is important to understand the reasons why the Annotation was created, not just the agents involved. These reasons are provided by declaring the motivation for the Annotations creation; the "why" rather than the "who" and "when" described in the previous sections.

Example Use Case:Dawn annotates a resource intending to provide a further description of it, perhaps for a screen reader to read aloud. Her client adds the right motivation to the Annotation to capture this.

Model

TermTypeURIDescription
MotivationClassoa:MotivationThe 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.
motivationRelationshipoa:motivatedByThe relationship between an Annotation and a Motivation.
There SHOULD be at least 1 Motivation for each Annotation, and MAY be more than 1.
Motivations
bookmarkingInstance oa:bookmarking 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.
classifyingInstance oa:classifying The motivation for when the user intends to that classify the Target as something. For example to classify an image as a portrait.
commentingInstance oa:commenting The motivation for when the user intends to comment about the Target. For example to provide a commentary about a particular PDF document.
describingInstance oa:describing The motivation for when the user intends to describe the Target, as opposed to a comment about them. For example describing the above PDF's contents, rather than commenting on their accuracy.
editingInstance oa:editing 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.
highlightingInstance oa:highlighting 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.
identifyingInstanceoa:identifyingThe motivation for when the user intends to assign an identity to the Target. For example to associate the URI that identifies a city with a mention of the city in a web page.
linkingInstanceoa:linkingThe motivation for when the user intends to link to a resource related to the Target.
moderatingInstance oa:moderating 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.
questioningInstance oa:questioning 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.
replyingInstance oa:replying 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.
reviewingInstanceoa:reviewing The motivation for when the user intends to review the Target in some assessing fashion, rather than simply make a comment about it. For example to write a review of a Book.
taggingInstance oa:tagging The motivation for when the user intends to associate a tag with the Target.
Note
For more information about how Motivations can be inter-related and new Motivations created, please see this appendix.

Example

Example 7: Motivations (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno4",
  "type": "Annotation",
  "motivation": "describing",
  "body": {"id": "http://example.org/description1"},
  "target": "http://example.com/resource1"
}

3.2 Bodies and Targets

The two main resources referenced from the Annotation are the Body and Target. While the Target is always an External Resource, the Body may be embedded within the Annotation graph. All of the features of External Resources may be used with Embedded Bodies.

3.2.1 External Resources

The Web is distributed, with different systems working together to provide access to content. Annotations can be used to link those resources together, being referenced as the Body and Target. Web Resources have identity via their URL, and have various properties, often including a format or language for the resource's content.

Example Use Case: Emily records a long analysis of a patent, and publishes it on her web site as an mp3. She then creates an Annotation with the PDF as the body, and the patent as the target.

Model

idProperty - The URI that identifies the Body or Target resource.
External Bodies or Targets MUST have exactly 1 id with the value of the resource's URI.
languagePropertydc:languageThe language of the textual body's content
The Body or Target SHOULD have exactly 1 language associated with it, but MAY have 0 or more. The value of the property SHOULD be a language code following the [rfc5646] specifiction.
formatPropertydc:formatThe format of the textual body's content
The Body or Target SHOULD have exactly 1 format associated with it, but MAY have 0. The value of the property SHOULD be the media-type of the format, following the [rfc6838] specification.

Example

Example 9: External Resources (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno5",
  "type": "Annotation",
  "body": {
    "id": "http://example.org/analysis1.mp3",
    "format": "audio/mpeg",
    "language": "fr"
  },
  "target": {
    "id": "http://example.gov/patent1.pdf",
    "format": "application/pdf",
    "language": "en"
  }
}
3.2.1.1 Creation Information

As the Target and Body may be created at a different time, and by a different agent, from the one that created the Annotation, creation information can be associated with the Body or Target resources body.

Example Use Case: Franceska writes a web page with a detailed walkthrough of a computer game. Gretchen later creates an Annotation with that page as the body, and the computer game as the target.

Model
TermTypeURIDescription
creatorRelationshipdcterms:creatorThe agent responsible for creating the Body or Target. This may be either a human or software agent.
There MAY be 1 or more creator relationships.
createdPropertydcterms:createdThe time at which the Body or Target was created.
There MAY be exactly 1 created property, and MUST NOT be more than 1. The datetime MUST be expressed in the xsd:dateTime format, and SHOULD have a timezone specified.
Example
Example 11: Creation Information (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno6",
  "type": "Annotation",
  "creator": {
    "id": "http://example.org/agent1",
    "type": "Person",
    "name": "A. Person",
    "nick": "agent1"
  },
  "body": {
    "id": "http://example.org/walkthrough1",
    "creator": {
      "id": "http://example.org/user1",
      "type": "Person",
      "name": "B. Person",
      "nick": "agent2"
    }
  },
  "target": {
    "id": "http://example.com/game1",
    "creator": {
      "id": "http://example.com/company1",
      "type": "Organization",
      "name": "Game Company"
    }
  }
}
3.2.1.2 Classes

It is useful for clients to know the general class of an External Body or Target in advance. If the client cannot render videos, then knowing that the Body is a video will allow it to avoid needlessly downloading a potentially large resource. For resources that do not have obvious media types, such as many data formats, it is also useful for a client to know that a resource with the format text/csv should not simply be rendered as plain text, despite the first part of the media type, whereas application/pdf may be able to be rendered by the user agent despite the main type being 'application'.

Example Use Case: Hannah shoots a video of her comment about a site on her phone and uploads it. She associates the video with the site via an Annotation, and her client adds types as a hint to consuming systems.

Model
TermTypeURIDescription
typeRelationshiprdf:typeThe type of the Body resource.
The Body MAY have a type, and if so, it SHOULD be drawn from the list below.
DatasetClassdctypes:DatasetThe class for a resource which encodes data in a defined structure
ImageClassdctypes:StillImageThe class for image resources, primarily intended to be seen
VideoClassdctypes:MovingImageThe class for video resources, with or without audio
SoundClassdctypes:SoundThe class for a resource primarily intended to be heard
TextClassdctypes:TextThe class for a resource primarily intended to be read
Example
Example 13: Typing of Body and Target (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno7",
  "type":"Annotation",
  "body": {
    "id":"http://example.org/video1",
    "type":"Video"
  },
  "target": {
    "id": "http://example.org/site1",
    "type": "Text"
  }
}
3.2.1.3 Segments of Exernal Resources

Many Annotations involve part of an external resource, rather than its entirety. In the Web [webarch], segments of resources are identified using URIs with a Fragment component that at the same time both describes how to extract the segment of interest from the resource, and identifies the extracted content. For simple Annotations, it is valuable to be able to use these Fragment URIs as the identifier of either Body or Target.

Example Use Case: Irina wants to describe a particular region of an image. She highlights that area in her client and types in the description. Her client then constructs the correct Fragment URI as the target.

Model
TermTypeURIDescription
idProperty - The Fragment URI that identifies the segment of the Body or Target resource.
External Bodies or Targets MUST have exactly 1 id with the value of the resource's URI, and this MAY be a Fragment URI.

It is important to be aware of the consequences of using a Fragment URI, and the restrictions that using them places on implementations.

  • Fragments are defined with respect to individual media types. For example, HTML has a specific set of semantics regarding the meaning of the Fragment part of the URI.
  • Not every media type has a fragment specification. For example, Office documents might have a media-type and be published on the web, but not have semantics associated with the Fragment part of the URI.
  • Even if a media type does have a fragment definition, it is often not possible to describe the segment of interest sufficiently precisely. For example, fragments for HTML cannot be used to describe an arbitrary range of text.
  • It is not possible to determine with certainty what is being identified without knowing the media type, as the same fragment string might be possible in different specifications. For example, the same fragment string could identify either a rectangular area in an image, or a strangely named section of an HTML document.
  • Fragment URIs are not compatible with other methods of describing the segment more specifically. For example, it is not possible to describe how to retrieve the correct representation, add style information, or associate a role with the resource, using Fragment URIs. The method to accomplish these requirements is described in the Fragment Selector portion of the Specific Resources section.
  • As URIs are considered to be opaque strings, annotation systems may not discover annotations with fragment URIs when searching by means of the URI without the fragment. For example, an Annotation with the Target http://example.com/image.jpg#xywh=1,1,1,1 would not be discovered in a simple search for http://example.com/image.jpg, even though it is part of it.
For more information regarding the use of Fragment URIs, please see the Best Practices for Fragment Identifiers and Media Type Definitions [fragid-best-practices].

Example
Example 15: Fragment URIs (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno8",
  "type": "Annotation",
  "body": {
    "id": "http://example.org/description1"
  },
  "target": {
    "id": "http://example.com/image1#xywh=100,100,300,300"
  }
}

3.2.2 Embedded Bodies

3.2.2.1 Textual Body

In many situations, the body of the Annotation will be in a text format, and created at the same time as the Annotation and not have a separate URI. In these cases, the Body's text can be included as part of the Annotation to avoid having to interact with multiple systems. The Body may also have the features of External Resources, including especially the language of the text and the format that it is conveyed in.

Example Use Case: Jane writes a comment about how much she likes an image on a photo sharing website. Her client creates an Annotation with the comment embedded within it, and adds that it is in French and formatted using HTML.

Model
The fundamental features of a textual body are:
TermTypeURIDescription
idProperty - The identity of the textual body
The Body MAY have exactly 1 http/https URI that identifies it.
typeRelationshiprdf:typeThe class of the Body
The Body MAY have the TextualBody class, and MAY have other classes.
TextualBodyClassoa:TextualBodyA class assigned to the Body for embedding textual resources within the Annotation.
textPropertyoa:textThe character sequence of the content.
There MUST be exactly 1 text property associated with the TextualBody.
languagePropertydc:languageThe language of the textual body's content
The textual body SHOULD have exactly 1 language associated with it, but MAY have 0 or more. The value of the property SHOULD be a language code following the [rfc5646] specifiction.
formatPropertydc:formatThe format of the textual body's content
The textual body SHOULD have exactly 1 format associated with it, but MAY have 0. The value of the property SHOULD be the media-type of the format, following the [rfc6838] specification.

Systems SHOULD assume that Textual Bodies have the Text class.

Example
Example 17: Textual Body (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno9",
  "type":"Annotation",
  "body": {
    "type" : "TextualBody",
    "text" : "<p>Comment text</p>",
    "format" : "text/html",
    "language" : "en"
  },
  "target": "http://example.org/photo1"
}
3.2.2.2 Inclusion Reason

In the same way that Annotations may have a Motivation for their creation, a Body may be included in the Annotation for a particular reason. This may be different from the Motivation for the creation of the Annotation.

Example Use Case: Kelly tags a web page that she wants to come back and read with "readme". The motiation for creating the annotation is bookmarking the page, and the role of the body is tagging that page with a particular string tag that she can later go back and search for.

Model
TermTypeURIDescription
roleRelationshipoa:hasRoleThe reason for including the Body in the Annotation.
There SHOULD be exactly 1 role for a Textual Body, and the value MUST be a Motivation

It is important to note that this feature cannot be used directly with External Resources in the same way as for TextualBody resources. See this section for how to structure roles with External Resources using a SpecificResource.

Example
Example 19: Tagging (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno10",
  "type":"Annotation",
  "motivation": "bookmarking",
  "body": {
    "text" : "readme",
    "role" : "tagging"
  },
  "target": "http://example.org/page1"
}
3.2.2.3 String Body

The simplest type of Body is a plain text string, without additional information or properties. This type of body is useful for the simplest of Annotations only, and is NOT RECOMMENDED for uses where the content of the body has any intellectual value or may need to be referred to from outside of the Annotation.

Example Use Case Megan wants to create a quick Annotation from a simple, command line client. She creates the JSON serialization in a text file and sends it to her Annotation server to maintain.

Model

There are several restrictions on when this form may be used and how it is to be interpreted.
The string body:

  • MUST be an xsd:string and the data type MUST NOT be expressed in the serialization.
  • MUST NOT have a language associated with it.
  • MUST be interpreted as if it were the value of the text property of a Textual Body.
  • MUST be interpreted as if the Textual Body resource had a format property with the value text/plain.
  • MUST be interpreted as if the Textual Body resource had a role property with the value of commenting.
  • MUST NOT have the value of other properties of the Textual Body inferred from similar properties on the Annotation resource.

Note

In order for the body value to be a URI, it MUST be in the {"id": "URI"} form, otherwise it will be considered a string literal. However, as target MUST NOT be a string literal, it MAY be given as either a string or in the JSON object form.

Issue 1
An alternative that would allow clients to avoid type checking and make the model more coherent under consideration is to use a separate property, bodyText, to record the text of the body.
TermTypeURIDescription
bodyTextPropertyoa:bodyTextThe string value of the body of the Annotation.
There MAY be exactly 1 bodyValue for an Annotation, and the value MUST conform to the requirements above.
Example
Example 21: String Body (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno11",
  "type":"Annotation",
  "body": "Comment text",
  "target": "http://example.org/target1"
}

4. Specific Resources

While it is possible using only the constructions in the core data model described above to create Annotations that reference parts of resources by using Fragment URIs, there are many situations when this is not sufficient. For example, even a simple circular region of an image, or a diagonal line across it, are not possible. Selecting an arbitrary span of text in an HTML page, perhaps the simplest annotation concept, is also not supported by fragment URIs. Furthermore, there are non-segment use cases that require a client to retrieve a specific state or representation of the resource, to style it in a particular way, to associate a role with the resource that is specific to the Annotation's use of it, or for the Annotation to only apply when the resource is used in a particular context.

The Web Annotation Data Model uses a new type of resource to capture these Annotation-specific requirements: a SpecificResource. The SpecificResource is used in between the Annotation and the Body or Target, as appropriate, to capture the additional description of how it is used in the Annotation. The descriptions are referenced from the SpecificResource as separate entities and can be of various types to capture the different requirements. For example, if the Target of the Annotation is a circular region of an image, then the SpecificResource is the circular region, it is described by a Selector, and is also associated with the source Image resource.

The types of additional specificity that are available:

The same Specifier classes are used for both Specific Target and Specific Body. The diagrams and examples in this section only depict one of these, however the same model applies for both.

Example Use Case: Noelle wants to make a comment about a circular region in an Image. She uses her client to draw the region and then writes her comment.

Model

TermTypeURIDescription
idProperty - The identity of the Specific Resource
A Specific Resource MAY have exactly 1 http/https URI that identifies it, or MAY have no identity.
typeRelationshiprdf:typeThe class of the Specific Resource
The Specific Resource MAY have the SpecificResource.
SpecificResourceClassoa:SpecificResourceThe class for Specific Resources
The SpecificResource class SHOULD be associated with a Specific Resource to be clear as to its role as a more specific region or state of another resource.
sourceRelationshipoa:hasSourceThe relationship between a Specific Resource and the resource that it is a more specific representation of.
There MUST be exactly 1 source relationship associated with a Specific Resource. The source resource MAY be described in detail as in the core data model or be just the resource's URI.
Issue 2

A future version of the specification may REQUIRE the use of SpecificResources for Body and Target in order to ensure consistency at the expense of additional structure.

Example

Example 23: Specific Resources (JSON)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno12",
  "type": "Annotation",
  "body": {"id": "http://example.org/comment1"},
  "target": {
    "id": "http://example.org/region1",
    "type": "SpecificResource",
    "source": "http://example.org/image1"
  }
}

4.1 Roles for External Resources

As well as Textual Bodies, roles can be associated with External Resources. This is done using the Specific Resource pattern, as the role specifies the way in which the resource is used in the context of the Annotation in the same way as a Selector describes the segment or a State describes the representation.

Example Use Case: Ophelia wants to tag a photo with an identifier for a city, rather than just type the city's name which could be ambiguous. Her client uses a well-known URI for the city having done a search for it, and creates a Specific Resource to manage the role.

Model

TermTypeURIDescription
roleRelationshipoa:hasRoleThe reason for including the External Resource in the Annotation.
There MAY be exactly 1 role associated with the SpecificResource, and the value MUST be a Motivation

Example

Example 25: Resource with Role (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno13",
  "type": "Annotation",
  "body": {
    "role": "tagging",
    "source": "http://example.org/city1"
  },
  "target": {
    "id": "http://example.org/photo1",
    "type": "Image"
  }
}

4.2 Selectors

Many Annotations refer to part of a resource, rather than all of it, as the Target. A Selector is used to describe how to determine the segment of interest from within the Source resource. The nature of the Selector will be dependent on the type of resource, as the methods to describe segments of different media-types will differ.

Example Use Case: Petra wants to associate a selection of text in a web page, with a slice of a dataset. She selects both using her client, and creates the Annotation with a SpecificResource that has a Selector for each of the Body and the Target.

Model

TermTypeURIDescription
selectorRelationshipoa:hasSelectorThe relationship between a Specific Resource and a Selector.
There MUST be exactly 0 or 1 selector relationships associated with a Specific Resource.

Example

Example 27: Selectors (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno14",
  "type": "Annotation",
  "body": {
    "source": "http://example.org/page1",
    "selector": "http://example.org/paraselector1"
  },
  "target": {
    "source": "http://example.com/dataset1",
    "selector": "http://example.org/dataselector1"
  }
}

4.2.1 Fragment Selector

As the most well understood mechanism for selecting a segment of a resource is to use the fragment defined by the representation's media type, it is useful to allow this as a description for a Selector. This allows existing and future fragment specifications to be used with Specific Resources in a consistent way. To be clear about which fragment type is being used, the Selector may refer to the specification that defines it.

Example Use Case: Qitara wants to associate part of a video as the description of an image. She selects the time range within the video and clicks that it is describing the target. Her client then creates the Annotation using a SpecificResource with a FragmentSelector and the describing Motivation.

Model

It is RECOMMENDED to use FragmentSelector as a consistent method compatible with other means of describing SpecificResources, rather than using the Fragment URI directly. Consuming applications SHOULD be aware of both.

TermTypeURIDescription
FragmentSelectorClassoa:FragmentSelectorA resource which describes the segment of interest in a representation, through the use of the fragment identifier component of a URI.
valuePropertyrdf:valueThe contents of the fragment identifier component of a URI that describes the segment of interest in the resource.
The FragmentSelector MUST have exactly 1 value property.
conformsToRelationshipdcterms:conformsToThe Fragment Selector SHOULD have a conformsTo link to the specification that defines the syntax of the fragment.

The following URIs are some of the specifications that define the semantics of fragments, and hence may be used with the conformsTo relationship. Other URIs MAY also be used.

Fragment SpecificationDescription
http://tools.ietf.org/rfc/rfc3236[rfc3236] Example: namedSection
http://tools.ietf.org/rfc/rfc3778[rfc3778] Example: page=10&viewrect=50,50,640,480
http://tools.ietf.org/rfc/rfc5147[rfc5147] Example: char=0,10
http://tools.ietf.org/rfc/rfc3023[rfc3023] Example: xpointer(/a/b/c)
http://tools.ietf.org/rfc/rfc3870[rfc3870] Example: namedResource
http://tools.ietf.org/rfc/rfc7111[rfc7111] Example: row=5-7
http://www.w3.org/TR/media-frags/[media-frags] Example: xywh=50,50,640,480
http://www.w3.org/TR/SVG/[SVG] Example: svgView(viewBox(50,50,640,480))
http://www.idpf.org/epub/linking/cfi/epub-cfi.html[CFI] Example: epubcfi(/6/4[chap01ref]!/4[body01]/10[para05]/3:10)

Note

A Fragment URI may be reconstructed by concatenating the source, a #, and the value.

Example

Example 29: Fragment Selector (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno15",
  "type": "Annotation",
  "target": {"id": "http://example.org/image1"},
  "body": {
    "source": "http://example.org/video1",
    "role": "describing",
    "selector": {
      "type": "FragmentSelector",
      "conformsTo": "http://www.w3.org/TR/media-frags/",
      "value": "t=30,60"
    }
  }
}

4.2.2 Text Quote Selector

This Selector describes a range of text by copying it, and including some of the text immediately before (a prefix) and after (a suffix) it to distinguish between multiple copies of the same sequence of characters.

For example, if the document were again "abcdefghijklmnopqrstuvwxyz", one could select "efg" by a prefix of "abcd", the match of "efg" and a suffix of "hijk".

Example Use Case: Ramona selects a typo (anotation) in a web page and adds a comment that it should be replaced with the correct spelling (annotation).

Model

TermTypeURIDescription
TextQuoteSelectorClassoa:TextQuoteSelectorThe class for a Selector that describes a textual segment by means of quoting it, plus passages before or after it.
The TextQuoteSelector MUST have this class associated with it, and SHOULD NOT have other classes.
exactPropertyoa:exactA copy of the text which is being selected, after normalization.
Each TextQuoteSelector MUST have exactly 1 exact property.
prefixPropertyoa:prefixA snippet of text that occurs immediately before the text which is being selected.
Each TextQuoteSelector SHOULD have exactly 1 prefix property, and MUST NOT have more than 1.
suffixPropertyoa:suffixThe snippet of text that occurs immediately after the text which is being selected.
Each TextQuoteSelector SHOULD have exactly 1 suffix property, and MUST NOT have more than 1.

The text MUST be normalized before recording. Thus HTML/XML tags should be removed, character entities should be replaced with the character that they encode, unnecessary whitespace should be normalized, character encoding should be turned into UTF-8, and so forth. The normalization routine may be performed automatically by a browser, and other applications should implement the DOM String Comparisons method. This allows the Selector to be used with different encodings and user agents and still have the same semantics and utility.

If, after processing the prefix, exact and suffix, the user agent discovers multiple matching text sequences, then the selection SHOULD be treated as matching all of the matches.

Note

If the content is under copyright or has other rights asserted on its use, then this method of selecting text is potentially dangerous. A user might select the entire text of the document to annotate, which would not be desirable to copy into the Annotation and share. For static texts with access and/or distribution restrictions, the use of the Text Position Selector is perhaps more appropriate.

Example

Example 31: Text Quote Selector (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno16",
  "type": "Annotation",
  "body": {"id": "http://example.org/comment1"},
  "target": {
    "source": "http://example.org/page1",
    "selector": {
      "type": "TextQuoteSelector",
      "exact": "anotation",
      "prefix": "this is an ",
      "suffix": " that has some"
    }
  }
}

4.2.3 Text Position Selector

This Selector describes a range of text by recording the start and end positions of the selection in the stream. Position 0 would be immediately before the first character, position 1 would be immediately before the second character, and so on. The start character is thus included in the list, but the end character is not.

For example, if the document was "abcdefghijklmnopqrstuvwxyz", the start was 4, and the end was 7, then the selection would be "efg".

Example Use Case: Sally writes a review of an ebook that does not allow its content to be extracted and copied. Her client describes the selection using its start and end position in the content.

Model

TermTypeURIDescription
TextPositionSelectorClassoa:TextPositionSelectorThe class for a Selector which describes a range of text based on its start and end positions.
The TextPositionSelector MUST have this class associated with it, and SHOULD NOT have other classes.
startPropertyoa:startThe starting position of the segment of text. The first character in the full text is character position 0, and the character is included within the segment.
Each TextPositionSelector MUST have exactly 1 start property, and the value MUST be a non-negative integer.
endPropertyoa:endThe end position of the segment of text. The character is not included within the segment.
Each TextPositionSelector MUST have exactly 1 end property, and the value MUST be a non-negative integer.

The text MUST be normalized before counting the characters, in the same way as for Text Quotation Selector.

Note

The use of this Selector does not require text to be copied from the Source document into the Annotation graph, unlike the Text Quote Selector, but is very brittle with regards to changes to the resource. Any edits may change the selection, and thus it is RECOMMENDED that a State be additionally used to help identify the correct representation.

Example

Example 33: Text Position Selector (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno17",
  "type": "Annotation",
  "body": {"id": "http://example.org/review1"},
  "target": {
    "source": "http://example.org/ebook1",
    "selector": {
      "type": "TextPositionSelector",
      "start": 412,
      "end": 795
    }
  }
}

4.2.4 Data Position Selector

Similar to the Text Position Selector, the Data Position Selector uses the same properties but works at the byte in bitstream level rather than the character in text level.

Example Use Case: Teynika writes comments about regions of online disk images for forensic purposes and describing emulation requirements. Her client generates the start and end positions from the binary stream, rather than the more human readable display she is using.

Model

TermTypeURIDescription
DataPositionSelectorClassoa:DataPositionSelectorThe class for a Selector which describes a range of data based on its start and end positions within the byte stream.
The DataPositionSelector MUST have this class associated with it, and SHOULD NOT have other classes.
startPropertyoa:startThe starting position of the segment of data. The first byte is character position 0.
Each DataPositionSelector MUST have exactly 1 start property.
endPropertyoa:endThe end position of the segment of data. The last character is not included within the segment.
Each DataPositionSelector MUST have exactly 1 end property.

Example

Example 35: Data Position Selector (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno18",
  "type": "Annotation",
  "body": {"id": "http://example.org/note1"},
  "target": {
    "source": "http://example.org/diskimg1",
    "selector": {
      "type": "DataPositionSelector",
      "start": 4096,
      "end": 4104
    }
  }
}

4.2.5 SVG Selector

An SvgSelector defines an area through the use of the Scalable Vector Graphics [SVG] standard. This allows the user to select a non-rectangular area of the content, such as a circle or polygon by describing the region using SVG. The SVG may be either embedded within the Annotation or referenced as an External Resource.

Example Use Case: Ulrika is tagging an old map online with a diagonal region for a historical road. Her client creates SVG polygon to describe the region, relative to the image content.

Model

TermTypeURIDescription
SvgSelectorClassoa:SvgSelectorThe class for a Selector which defines a shape for the selected area using the SVG standard.
The Selector MUST have this class associated with it and MAY also have the EmbeddedContent class associated with it.
EmbeddedContentClassoa:EmbeddedContentThe class for resources Embedded in the Annotation graph, other than Textual Bodies.
If the content of the SVG description is embedded within the Graph, then the Selector MUST have this class associated with it as well as the SvgSelector class.
textPropertyoa:textThe character sequence of the SVG content.
There MAY be exactly 1 text property associated with the Selector, and if so the value of the property MUST be well-formed SVG XML.
formatPropertydc:formatThe format of the content.
The Selector MAY have exactly 1 format associated with it. If present, the value of the property MUST be the SVG media-type of image/svg+xml.

The dimensions of the SVG shape or canvas MUST be relative to the dimensions of the Source resource, such that scaling the shape's size to the full size of the image correctly describes the desired area.

It is NOT RECOMMENDED to include style information within the SVG element, nor Javascript, animation, text or other non-shape oriented information. Clients SHOULD ignore such information if present.

Example

Example 37: SVG Selector (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno19",
  "type": "Annotation",
  "body": {"id": "http://example.org/road1"},
  "target": {
    "source": "http://example.org/map1",
    "selector": {
      "id": "http://example.org/svg1",
      "type": "SvgSelector"
    }
  }
}
Example 39: SVG Selector, embedded (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno20",
  "type": "Annotation",
  "body": {"id": "http://example.org/road1"},
  "target": {
    "source": "http://example.org/map1",
    "selector": {
      "type": ["SvgSelector", "EmbeddedContent"],
      "text": "<svg:svg> ... </svg:svg>",
      "format": "image/svg+xml"
    }
  }
}

4.3 States

A State describes the intended state of a resource as applied to the particular Annotation, and thus provides the information needed to retrieve the correct representation of that resource. Web resources change over time, and a State might be used to describe how to recover the intended previous version. Web resources also have multiple formats, and a State might equally be used to describe how to retrieve that particular format.

Example Use Case: Valeria makes a comment about a web page that changes frequently. Her client records information to allow other clients to hopefully reconstruct the original target of the annotation.

Model

TermTypeURIDescription
stateRelationshipoa:hasStateThe relationship between the SpecificResource and the State.
There MAY be 1 or more state relationships for each SpecificResource.

States MUST be processed before processing Selector or Style information.

Example

Example 41: State (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno21",
  "type": "Annotation",
  "body": {"id": "http://example.org/note1"},
  "target": {
    "source": "http://example.org/page1",
    "state": {
      "id": "http://example.org/state1"
    }
  }
}

4.3.1 Time State

A Time State resource records the time at which the resource is appropriate for the Annotation, typically the time that the Annotation was created and/or a link to a persistent copy of the current version.

Example Use Case: Wendy makes a note about the current state of the front page of a news website, and flags that the page is likely to change often. Her client adds in a State with the current time to describe the version of the page being annotated.

Model

TermTypeURIDescription
TimeStateClassoa:TimeStateA descriptoin of how to retrieve a representation of the Source resource that is temporally appropriate for the Annotation.
The State MUST have this class associated with it.
sourceDatePropertyoa:sourceDateThe timestamp at which the Source resource should be interpreted for the Annotation, potentially to resolve via the Memento protocol [rfc7089].
There MAY be 0 or more sourceDate properties per TimeState, but there MUST be at least one of sourceDate and cachedSource. If there is more than 1, each gives an alternative timestamp at which the Source may be interpreted. The timestamp MUST be expressed in the xsd:dateTime format, and SHOULD have a timezone specified.
cachedRelationshipoa:cachedSourceA link to a copy of the Source resource's representation, appropriate for the Annotation.
There MAY be 0 or more cached relationships per TimeState, but there MUST be at least one of cached and sourceDate. If there is more than 1, each gives an alternative copy of the representation.

Example

Example 43: Time State (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno22",
  "type": "Annotation",
  "body": {"id": "http://example.org/note1"},
  "target": {
    "source": "http://example.org/page1",
    "state": {
      "type": "TimeState",
      "cached": "http://archive.example.org/copy1",
      "sourceDate": "2015-07-20T13:30:00Z"
    }
  }
}

4.3.2 Request Header State

As there are potentially many representations that can be delivered from a resource with a single URI, and a Specific Resource may only apply to one of them, it is important to be able to record the HTTP Request headers that need to be sent to retrieve the correct representation. The HttpRequestState resource maintains a copy of the headers to be replayed when obtaining the representation.

Example Use Case: Xena retrieves a PDF representation of a web resource that can deliver HTML, PDF or plain text and then writes a description about it. She signals that her description is only about the PDF representation. Her client then includes a State to describe how to retrieve the target representation.

Model

TermTypeURIDescription
HttpRequestStateClassoa:HttpRequestStateA description of how to retrieve an appropriate representation of the Source resource for the Annotation, based on the HTTP Request headers to send on the request.
The State MUST have this class associated with it.
valuePropertyrdf:valueThe HTTP request headers to send as a single, complete string.
An HttpRequestState MUST have exactly 1 value property.

Example

Example 45: HTTP Request State (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno23",
  "type": "Annotation",
  "body": {"id": "http://example.org/description1"},
  "target": {
    "source": "http://example.org/resource1",
    "state": {
      "type": "HttpRequestState",
      "value": "Accept: application/pdf"
    }
  }
}

4.4 Styles

The interpretation of a particular Annotation may rely on rendering style being consistent across implementations. Rendering information is recorded using CSS stylesheets [CSS2] and references to classes defined in those stylesheets.

Example Use Case: Yadira highlights two sections of a document, one in red and the other in yellow. She then makes a comment that the yellow part contradicts the red part. Her client records the red and yellow coloration of the targets.

Model

TermTypeURIDescription
CssStylesheetClassoa:CssStyleA resource which describes styles for resources participating in the Annotation using CSS.
stylesheetRelationshipoa:styledByThe relationship between an Annotation and the Style.
There MAY be 0 or 1 stylesheet relationships for each Annotation.
styleClassPropertyoa:styleClassThe name of the class used in the CSS description that should be applied to the Specific Resource.
There MAY be 0 or more styleClass properties on a Specific Resource.

The CSS Stylesheet is associated with the Annotation itself, and the content provides the rendering hints about the Annotation's constituent resources. It MAY have its own dereferenceable URI that provides the information, or it may be embedded within the Annotation. This is to avoid having single line stylesheets each associated with different resources, and instead to allow reference to a single URI that governs the full set of styles for a particular implementation.

Publishing systems MUST NOT assume that they will be processed; they are only provided as hints rather than requirements.

When rendering a Specific Resource, consuming applications SHOULD check to see if it has a styleClass property. If it does, then the application SHOULD attempt to locate the appropriate selector in the CSS document, and then apply the css-value block. If a Specific Resource has a styleClass value, but no such class is described by a stylesheet attached to the Annotation, then the styleClass MUST be ignored.

Example

Example 47: CSS Style (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno24",
  "type": "Annotation",
  "stylesheet": {
    "id": "http://example.org/style1",
    "type": "CssStylesheet"
  },
  "body": {"id": "http://example.org/comment1"},
  "target": {
    "source": "http://example.org/document1",
    "styleClass": "red"
  }
}
Example 49: CSS Style, embedded (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno25",
  "type": "Annotation",
  "stylesheet": {
    "type": ["CssStylesheet", "EmbeddedContent"],
    "value": ".red { color: red }",
    "format": "text/css"
  },
  "body": {"id": "http://example.org/body1"},
  "target": {
    "source": "http://example.org/target1",
    "styleClass": "red"
  }
}

4.5 Scope of a Resource

It is sometimes important for an Annotation to capture the context in which it was made, in terms of the resources that the annotator was viewing or using at the time. This does not imply an assertion that the annotation is only valid for the image in the context of that page, it just records that the page was being viewed.

Example Use Case: Zara makes a comment about an image in a particular web page to say that it is not the right organization's logo. Her client includes the page that the image is being rendered in, however the annotation is associated with the image resource itself.

Model

TermTypeURIDescription
scopeRelationshipoa:hasScopeThe relationship between a Specific Resource and the resource that provides the scope or context for it in this Annotation.
There MAY be 0 or more scope relationships for each Specific Resource.

Example

Example 51: Scope (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno26",
  "type": "Annotation",
  "body": {"id": "http://example.org/note1"},
  "target": {
    "source": "http://example.org/image1",
    "scope": "http://example.org/page1"
  }
}

5. Multiplicity

5.1 Annotations without a Body

Some Annotations may not have a Body at all. This is permitted by the model, and applications should expect to encounter such Annotations.

Example Use Case: Alexandra highlights a particular region of her ebook in green and, knowing what such a highlight means, she does not give a comment. Her client associates a Stylesheet with the Annotation, and does not artificially create a body.

Model

The body property is omitted when there is no body for the Annotation.

Example

Example 53: Annotations without a Body (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno27",
  "type": "Annotation",
  "target": "http://example.org/ebook1"
}

5.2 Multiple Bodies or Targets

It is also possible for an Annotation to have multiple Bodies and/or Targets. Each Body is considered to be equally related to each Target individually, rather than to the set of Targets.

Example Use Case: Britney associates a tag and a description with two images using a single annotation.

Model

The body and/or target relationships of the Annotation may be arrays rather than a single object.

Example

Example 55: Multiple Bodies or Targets (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno28",
  "type": "Annotation",
  "body": [
    {
      "role": "describing",
      "source": "http://example.org/description1"
    },
    {
      "role": "tagging",
      "text": "tag1"
    }
  ],
  "target": [
    "http://example.org/image1",
    "http://example.org/image2"
  ]
}

5.3 Multiplicity Constructs

If the relationship between the bodies and targets of an Annotation are more complex than simply each of the bodies being about each of the targets, then additional constructions are required. These constructions, called Multiplicity Constructs, can express a Choice of alternatives, a Composite set of unordered objects, or an ordered List. The same constructions can also be used to express those same patterns between descriptions associated with Specific Resources, such as a List of Selectors, or a Choice of States.

The option of having a simple string literal for the body is not possible when using Multiplicity constructs, and the embedded textual body resource pattern MUST be used.

5.3.1 Choice

A Choice has an ordered list of resources from which an application should select only one to process or display. The order is given from the most preferable to least preferable, according to the Annotation's creator or publisher.

Example Use Case: Carla writes up her discussion of a particular site in both French and English. As the two posts are equivalent, there is no need to display both, and instead she wants French speakers to see the French comment, and everyone else to see the English version. Her client creates as Choice with the English comment listed first.

Model

TermTypeURIDescription
ChoiceClassoa:ChoiceA multiplicity construct that conveys to a consuming application that it should select one of the constituent resources to display to the user, and not render all of them.
membersRelationshipoa:memberListA list of resources to choose from, with the default to use listed first.

Clients MAY use any algorithm to determine which resource to choose, and SHOULD make use of the information present to do so automatically, but MAY present a list and require the user to make the decision.

Example

Example 57: Choice (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno29",
  "type": "Annotation",
  "body": {
    "type": "Choice",
    "members": [
      {
        "id": "http://example.org/note1",
        "language": "en"
      },
      {
        "id": "http://example.org/note2",
        "language": "fr"
      }
    ]
  },
  "target": "http://example.org/site1"
}

5.3.2 Composite

A Composite is a set of resources that are all required for an Annotation to be correctly interpreted.

Example Use Case: Devina writes a comparison of the differences between two online comics, both of which are required to understand the discussion.

Model

TermTypeURIDescription
CompositeClassoa:CompositeA multiplicity construct that conveys to a consuming application that all of the constituent resources are required for the Annotation to be correctly interpreted.
itemRelationshipoa:itemThe relationship between a Composite and its constituent resources.
A Composite MUST have 1 or more items.

Example

Example 59: Composite (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno30",
  "type": "Annotation",
  "body": {"id": "http://example.org/comparison1"},
  "target": {
    "type": "Composite",
    "item": [
      "http://example.org/comic1",
      "http://example.org/comic2"
    ]
  }
}

5.3.3 List

A List is a construct that provides an order to its constituent resources in the context of the Annotation.

Example Use Case: Erin selects a paragraph in a web page, and then highlights a span of text within it to write her comment about. Her client conveys this by creating a List with two selectors, the first picks the paragraph, and the second the span of text, relative to the paragraph rather than the entire document.

Model

TermTypeURIDescription
ListClassoa:ListA multiplicity construct that conveys to a consuming application that all of the constituent resources are required for the Annotation to be correctly interpreted, and in a particular order.
membersRelationshipoa:memberListA list of resources to use in order.

Example

Example 61: List (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno31",
  "type": "Annotation",
  "body": {"id": "http://example.org/comment1"},
  "target": {
    "source": "http://example.org/page1",
    "selector": {
      "type": "List",
      "members": [
        "http://example.org/paraselector1",
        "http://example.org/offsetselector1"
      ]
    }
  }
}

A. Namespaces

The Web Annotation Data Model defines a namespace for its classes and properties, and uses several others as listed below. The namespace URI will always remain the same, even if the data model changes.

The following namespaces are used in this specification:

PrefixNamespaceDescription
oahttp://www.w3.org/ns/oa# The Web Annotation Data Model
dchttp://purl.org/dc/elements/1.1/[DC11]
dctermshttp://purl.org/dc/terms/[DC-TERMS]
dctypeshttp://purl.org/dc/dcmitype/[DC-TERMS]
foafhttp://xmlns.com/foaf/0.1/[FOAF]
provhttp://www.w3.org/ns/prov#[prov-o]
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#[rdf-schema]
rdfshttp://www.w3.org/2000/01/rdf-schema#[rdf-schema]
skoshttp://www.w3.org/2004/02/skos/core#[skos-reference]
xsdhttp://www.w3.org/2001/XMLSchema#[xmlschema-2]

B. JSON-LD Considerations

The RECOMMENDED serialization format is [JSON-LD]. The JSON-LD context presented below is RECOMMENDED to ensure consistency between implementations, and SHOULD be referenced as http://www.w3.org/ns/anno.jsonld. It has a profile URI that SHOULD be used: http://www.w3.org/TR/annotation-model/jsonLdProfile. Beyond the annotation model, it also contains terms needed for the [annotation-protocol], adoption of which is RECOMMENDED.

{
 "@context": {
    "oa":      "http://www.w3.org/ns/oa#",
    "dc":      "http://purl.org/dc/elements/1.1/",
    "dcterms": "http://purl.org/dc/terms/",
    "dctypes": "http://purl.org/dc/dcmitype/",
    "foaf":    "http://xmlns.com/foaf/0.1/",
    "rdf":     "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "rdfs":    "http://www.w3.org/2000/01/rdf-schema#",
    "skos":    "http://www.w3.org/2004/02/skos/core#",
    "xsd":     "http://www.w3.org/2001/XMLSchema#",
    "ldp":     "http://www.w3.org/ns/ldp#",
    "iana":    "http://www.iana.org/assignments/relation/",
    "owl":     "http://www.w3.org/2002/07/owl#",
    "as":      "http://www.w3.org/ns/activitystreams#",

    "id":      "@id",
    "type":    "@type",

    "Annotation":           "oa:Annotation",
    "Dataset":              "dctypes:Dataset",
    "Image":                "dctypes:StillImage",
    "Video":                "dctypes:MovingImage",
    "Audio":                "dctypes:Sound",
    "Text":                 "dctypes:Text",
    "EmbeddedContent":      "oa:EmbeddedContent",
    "TextualBody":          "oa:TextualBody",
    "SpecificResource":     "oa:SpecificResource",
    "FragmentSelector":     "oa:FragmentSelector",
    "TextQuoteSelector":    "oa:TextQuoteSelector",
    "TextPositionSelector": "oa:TextPositionSelector",
    "DataPositionSelector": "oa:DataPositionSelector",
    "SvgSelector":          "oa:SvgSelector",
    "TimeState":            "oa:TimeState",
    "HttpState":            "oa:HttpRequestState",
    "CssStylesheet":        "oa:CssStyle",
    "Choice":               "oa:Choice",
    "Composite":            "oa:Composite",
    "List":                 "oa:List",
    "Person":               "foaf:Person",
    "Sofware":              "prov:SoftwareAgent",
    "Organization":         "foaf:Organization",
    "Container":            "ldp:BasicContainer",
    "DirectContainer":      "ldp:DirectContainer",
    "IndirectContainer":    "ldp:IndirectContainer",
    "Collection":           "as:Collection",
    "OrderedCollection":    "as:OrderedCollection",
    "OrderedCollectionPage": "as:OrderedCollectionPage",

    "Motivation":    "oa:Motivation",
    "bookmarking":   "oa:bookmarking",
    "classifying":   "oa:classifying",
    "commenting":    "oa:commenting",
    "describing":    "oa:describing",
    "editing":       "oa:editing",
    "highlighting":  "oa:highlighting",
    "identifying":   "oa:identifying",
    "linking":       "oa:linking",
    "moderating":    "oa:moderating",
    "questioning":   "oa:questioning",
    "replying":      "oa:replying",
    "reviewing":     "oa:reviewing",
    "tagging":       "oa:tagging",

    "body":          {"@id": "oa:hasBody"},
    "target":        {"@type": "@id", "@id": "oa:hasTarget"},
    "source":        {"@type": "@id", "@id": "oa:hasSource"},
    "selector":      {"@type": "@id", "@id": "oa:hasSelector"},
    "state":         {"@type": "@id", "@id": "oa:hasState"},
    "scope":         {"@type": "@id", "@id": "oa:hasScope"},
    "creator":       {"@type": "@id", "@id": "dcterms:creator"},
    "generator":     {"@type": "@id", "@id": "prov:generatedBy"},
    "motivation":    {"@type": "@id", "@id": "oa:motivatedBy"},
    "stylesheet":    {"@type": "@id", "@id": "oa:styledBy"},
    "cached":        {"@type": "@id", "@id": "oa:cachedSource"},
    "conformsTo":    {"@type": "@id", "@id": "dcterms:conformsTo"},
    "members":       {"@type": "@id", "@id": "oa:memberList", "@container": "@list"},
    "item":          {"@type": "@id", "@id": "oa:item"},
    "orderedItems":  {"@type": "@id", "@id": "as:items", "@container": "@list"},
    "partOf":        {"@type": "@id", "@id": "as:partOf"},
    "first":         {"@type": "@id", "@id": "as:first"},
    "last":          {"@type": "@id", "@id": "as:last"},
    "next":          {"@type": "@id", "@id": "as:next"},
    "prev":          {"@type": "@id", "@id": "as:prev"},
    "contains":      {"@type": "@id", "@id": "ldp:contains"},
    "membersIn":     {"@type": "@id", "@id": "ldp:membershipResource"},
    "memberRel":     {"@type": "@id", "@id": "ldp:hasMemberRelation"},
    "memberOfRel":   {"@type": "@id", "@id": "ldp:isMemberOfRelation"},
    "contentRel":    {"@type": "@id", "@id": "ldp:insertedContentRelation"},

    "format":        "dc:format",
    "language":      "dc:language",
    "created":       "dcterms:created",
    "generated":     "prov:generatedAtTime",
    "text":          "oa:text",
    "value":         "rdf:value",
    "start":         "oa:start",
    "end":           "oa:end",
    "exact":         "oa:exact",
    "prefix":        "oa:prefix",
    "suffix":        "oa:suffix",
    "sourceDate":    "oa:sourceDate",
    "styleClass":    "oa:styleClass",
    "label":         "rdfs:label",
    "name":          "foaf:name",
    "mbox":          "foaf:mbox",
    "nick":          "foaf:nick",
    "totalItems":    "as:totalItems"
  }
}

C. Complete Example

Entirely Contrived Example Use Case: Felicity wants to associate a comment that she wrote in English within the annotation or a external mp3 of the same content in German by someone else, plus a tag, with a range of characters from a particular element in an XML representation of a document as it was at a certain point in time, and for it to be displayed in a particular way.

Example 63: Complete Example (JSON-LD)
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno32",
  "type": "Annotation",
  "motivation": "commenting",
  "creator": {
    "id": "http://example.org/user1",
    "type": "Person",
    "name": "A. Person",
    "nick": "user1"
  },
  "created": "2015-10-13T13:00:00Z",
  "generator": {
    "id": "http://example.org/client1",
    "type": "SoftwareAgent",
    "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",
      "role": "tagging",
      "text": "love"
    },
    {
      "type": "Choice",
      "members": [
        {
          "type": "TextualBody",
          "role": "describing",
          "text": "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",
          "role": "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"
      },
      {
        "type": "TimeState",
        "sourceDate": "2015-09-25T12:00:00Z"
      }
    ],
    "selector": {
      "type": "List",
      "members": [
        {
          "type": "FragmentSelector",
          "value": "xpointer(/doc/body/section[2]/para[1])"
        },
        {
          "type": "TextPositionSelector",
          "start": 6,
          "end": 27
        }
      ]
    }
  }
}

D. Extending Motivations

Although the list of Motivations in the specification is derived from an extensive survey of the annotation landscape, there are many situations where more precise definitions are required or desirable. In these cases it is RECOMMENDED to create a new Motivation resource and relate it to one or more that already exist.

New Motivations MUST be instances of oa:Motivation, which is a subClass of skos:Concept. The skos:broader relationship SHOULD be asserted between the new Motivation and at least one existing Motivation, if there are any that are broader in scope. Other relationships, such as skos:relatedMatch, skos:exactMatch and skos:closeMatch, SHOULD also be asserted to concepts created by other communities.

Model

Extending Motivations
Fig. 1 Extending Motivations

E. Acknowledgements

The Web Annotation Working Group gratefully acknowledges the contributions of the Open Annotation Community Group. The output of the Community Group was fundamental to the current data model.

Changes in this specification from the Community Group's model are:

F. References

F.1 Informative references

[CSS2]
Bert Bos; Tantek Çelik; Ian Hickson; Håkon Wium Lie et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/CSS2
[DC-TERMS]
Dublin Core Metadata Initiative. Dublin Core Metadata Initiative Terms, version 1.1. 11 October 2010. DCMI Recommendation. URL: http://dublincore.org/documents/2010/10/11/dcmi-terms/.
[DC11]
Dublin Core metadata initiative. Dublin Core metadata element set, version 1.1. July 1999. Dublin Core recommendation. URL: http://dublincore.org/documents/dcmi-terms/
[FOAF]
Dan Brickley; Libby Miller. FOAF Vocabulary Specification 0.99 (Paddington Edition). 14 January 2014. URL: http://xmlns.com/foaf/spec
[JSON-LD]
Manu Sporny; Gregg Kellogg; Markus Lanthaler. JSON-LD 1.0. 16 January 2014. W3C Recommendation. URL: http://www.w3.org/TR/json-ld/
[SVG]
Jon Ferraiolo. Scalable Vector Graphics (SVG) 1.0 Specification. 4 September 2001. W3C Recommendation. URL: http://www.w3.org/TR/SVG/
[Turtle]
Eric Prud'hommeaux; Gavin Carothers. RDF 1.1 Turtle. 25 February 2014. W3C Recommendation. URL: http://www.w3.org/TR/turtle/
[annotation-protocol]
Robert Sanderson. Web Annotation Protocol. 2 July 2015. W3C Working Draft. URL: http://www.w3.org/TR/annotation-protocol/
[fragid-best-practices]
Jeni Tennison. Best Practices for Fragment Identifiers and Media Type Definitions. 25 October 2012. W3C Last Call Working Draft. URL: http://www.w3.org/TR/fragid-best-practices/
[media-frags]
Raphaël Troncy; Erik Mannens; Silvia Pfeiffer; Davy Van Deursen. Media Fragments URI 1.0 (basic). 25 September 2012. W3C Recommendation. URL: http://www.w3.org/TR/media-frags/
[prov-o]
Timothy Lebo; Satya Sahoo; Deborah McGuinness. PROV-O: The PROV Ontology. 30 April 2013. W3C Recommendation. URL: http://www.w3.org/TR/prov-o/
[rdf-schema]
Dan Brickley; Ramanathan Guha. RDF Schema 1.1. 25 February 2014. W3C Recommendation. URL: http://www.w3.org/TR/rdf-schema/
[rfc2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[rfc3023]
M. Murata; S. St. Laurent; D. Kohn. XML Media Types. January 2001. Proposed Standard. URL: https://tools.ietf.org/html/rfc3023
[rfc3236]
M. Baker; P. Stark. The 'application/xhtml+xml' Media Type. January 2002. Informational. URL: https://tools.ietf.org/html/rfc3236
[rfc3778]
E. Taft; J. Pravetz; S. Zilles; L. Masinter. The application/pdf Media Type. May 2004. Informational. URL: https://tools.ietf.org/html/rfc3778
[rfc3870]
A. Swartz. application/rdf+xml Media Type Registration. September 2004. Informational. URL: https://tools.ietf.org/html/rfc3870
[rfc5147]
E. Wilde; M. Duerst. URI Fragment Identifiers for the text/plain Media Type. April 2008. Proposed Standard. URL: https://tools.ietf.org/html/rfc5147
[rfc5646]
A. Phillips, Ed.; M. Davis, Ed.. Tags for Identifying Languages. September 2009. Best Current Practice. URL: https://tools.ietf.org/html/rfc5646
[rfc6838]
N. Freed; J. Klensin; T. Hansen. Media Type Specifications and Registration Procedures. January 2013. Best Current Practice. URL: https://tools.ietf.org/html/rfc6838
[rfc7089]
H. Van de Sompel; M. Nelson; R. Sanderson. HTTP Framework for Time-Based Access to Resource States -- Memento. December 2013. Informational. URL: https://tools.ietf.org/html/rfc7089
[rfc7111]
M. Hausenblas; E. Wilde; J. Tennison. URI Fragment Identifiers for the text/csv Media Type. January 2014. Informational. URL: https://tools.ietf.org/html/rfc7111
[skos-reference]
Alistair Miles; Sean Bechhofer. SKOS Simple Knowledge Organization System Reference. 18 August 2009. W3C Recommendation. URL: http://www.w3.org/TR/skos-reference
[webarch]
Ian Jacobs; Norman Walsh. Architecture of the World Wide Web, Volume One. 15 December 2004. W3C Recommendation. URL: http://www.w3.org/TR/webarch/
[xmlschema-2]
Paul V. Biron; Ashok Malhotra. XML Schema Part 2: Datatypes Second Edition. 28 October 2004. W3C Recommendation. URL: http://www.w3.org/TR/xmlschema-2/