Abstract

The Web Annotation Vocabulary specifies the set of RDF classes, predicates and named entities that are used by the Web Annotation Data Model [web-annotation]. It also lists recommended terms from other ontologies that are used in the model, and provides the JSON-LD Context and profile definitions needed to use the Web Annotation JSON serialization in a Linked Data context.

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!

Note
The content of this document, along with the latest release of the Web Annotation Data Model [web-annotation] specification, is the result of the split of the previous release of the previous release of the Web Annotation Data Model Working Draft into two documents.
Issue 1

The use of the W3CDTF format, instead of the more restrictive but more common xsd:datetime format, is considered to be at-risk.

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.

1. Introduction

This section is non-normative.

The specification is divided into two major sections: the terms defined in the Web Annotation ontology, and terms from other ontologies used in the model.

Each class lists the recommendations from the model for the REQUIRED, RECOMMENDED and OPTIONAL object and data properties for instances of the class. Instances may, of course, be the subject of any other triples that implementers find useful, however there is no expectation of interoperability in these cases.

1.1 Namespaces

PrefixNamespaceDescription
oahttp://www.w3.org/ns/oa# The Web Annotation Data Model
ashttp://www.w3.org/ns/activitystreams#[activitystreams-vocabulary]
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]
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#[rdf-schema]
rdfshttp://www.w3.org/2000/01/rdf-schema#[rdf-schema]
schemahttp://schema.org/schema.org
skoshttp://www.w3.org/2004/02/skos/core#[skos-reference]
xsdhttp://www.w3.org/2001/XMLSchema#[xmlschema-2]

1.2 Diagrams and Examples

The examples throughout the document are serialized as [Turtle] with the prefixes taken from the namespace declarations given in Appendix A. The examples are informative only.

The diagrams use the following style

Issue 2
The diagrams have yet to be completed (Github Issue).

1.3 Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, and SHOULD are to be interpreted as described in [RFC2119].

2. Web Annotation Ontology

The namespace used for the Web Annotation Ontology is: http://www.w3.org/ns/oa#

2.1 Classes

Annotation | Choice | Content | CssSelector | CssStyle | DataPositionSelector | FragmentSelector | HttpRequestState | Motivation | RangeSelector | ResourceSelection | Selector | SpecificResource | State | Style | SvgSelector | TextPositionSelector | TextQuoteSelector | TextualBody | TimeState | XPathSelector

2.1.1 Annotation

The class for Web Annotations.

oa:Annotation with properties
Example 1: oa:Annotation
<http://example.org/anno1> a oa:Annotation ;
    oa:hasBody <http://example.org/post1> ;
    oa:hasTarget <http://example.com/page1> ;
    oa:motivatedBy oa:commenting ;
    dcterms:creator <http://example.org/person1> ;
    dcterms:created "2015-11-18T12:00:00Z" .

2.1.2 Choice

A subClass of as:OrderedCollection that conveys to a consuming application that it should select one of the resources in the as:items list to use, rather than all of them. This is typically used to provide a choice of resources to render to the user, based on further supplied properties. If the consuming application cannot determine the user's preference, then it should use the first in the list.

oa:Choice with list of items
Example 2: oa:Choice
<http://example.org/anno2> a oa:Annotation ;
    oa:hasTarget <http://example.org/site1> ;
    oa:hasBody [
        a oa:Choice ;
        as:items (<http://example.org/note1> <http://example.org/note2>) ] .

<http://example.org/note1> dc:language "en" .
<http://example.org/note2> dc:language "fr" .

2.1.3 Content

The class for resources embedded in the Annotation graph, other than for textual content that is the object of the hasBody relationship.

Example 3: oa:Content
<http://example.org/anno3> a oa:Annotation ;
    oa:hasBody <http://example.org/body1> ;
    oa:styledBy [
        a oa:CssStyle, oa:Content ;
        dc:format "text/css" ;
        oa:text ".red { color: red }" ] ;
    oa:hasTarget [
        oa:hasSource <http://example.org/target1> ;
        oa:styleClass "red" ] .

2.1.4 CssSelector

A CssSelector describes a Segment of interest in a representation that conforms to the Document Object Model through the use of the CSS selector specification.

  • URI: http://www.w3.org/ns/oa#CssSelector
  • Sub Class Of: oa:Selector
Example 4
<http://example.org/anno4> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
            a oa:CssSelector ;
            rdf:value "#elemid > .elemclass + p" ] ] .

2.1.5 CssStyle

A resource which describes styles for resources participating in the Annotation using CSS.

  • URI: http://www.w3.org/ns/oa#CssStyle
  • Sub Class Of: oa:Style
Example 5
<http://example.org/anno5> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:styledBy <http://example.org/style1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/document1> ;
        oa:styleClass "red" ] .

<http://example.org/style1> a oa:CssStyle .

2.1.6 DataPositionSelector

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

Example 6: oa:DataPositionSelector
<http://example.org/anno6> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/diskimg1> ;
        oa:hasSelector [
            a oa:DataPositionSelector ;
            oa:start 4096 ;
            oa:end 4104 ] ] .

2.1.7 FragmentSelector

The FragmentSelector class is used to record the segment of a representation using the URI fragment specification defined by the representation's media type.

Example 7: oa:FragmentSelector
<http://example.org/anno7> a oa:Annotation ;
    oa:hasTarget <http://example.org/image1> ;
    oa:hasBody [
        oa:hasSource <http://example.org/video1> ;
        oa:hasPurpose oa:describing ;
        oa:hasSelector [
            a oa:FragmentSelector ;
            dcterms:conformsTo <http://www.w3.org/TR/media-frags/> ;
            rdf:value "t=30,60" ] ] .

2.1.8 HttpRequestState

The HttpRequestState class is used to record the HTTP request headers that a client SHOULD use to request the correct representation from the resource.

  • URI: http://www.w3.org/ns/oa#HttpRequestState
  • Sub Class Of: oa:State
  • Required Predicates: rdf:value
Example 8: oa:HttpRequestState
<http://example.org/anno8> a oa:Annotation ;
    oa:hasBody <http://example.org/description1> ;
    oa:hasTarget  [
        oa:hasSource <http://example.org/target1> ;
        oa:hasState [
            a oa:HttpRequestState ;
            rdf:value "Accept: text/plain" ] ] .

2.1.9 Motivation

The Motivation class is used to record the user's intent or motivation for the creation of the Annotation, or the inclusion of the body or target, that it is associated with.

Example 9: oa:Motivation
<http://example.org/anno9> a oa:Annotation ;
    oa:hasBody <http://example.org/description1> ;
    oa:hasTarget <http://example.com/resource1> ;
    oa:motivatedBy oa:describing .

2.1.10 RangeSelector

A Range Selector can be used to identify the beginning and the end of the selection by using other Selectors. The selection consists of everything from the beginning of the starting selector through to the beginning of the ending selector, but not including it.

Example 10: oa:RangeSelector
<http://example.org/anno10> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
          a oa:RangeSelector ;
          oa:hasStartSelector [
            a oa:XPathSelector ;
            rdfs:value "//table[1]/tr[1]/td[2]" ] ;
          oa:hasEndSelector [
            a oa:XPathSelector ;
            rdfs:value "//table[1]/tr[1]/td[4]" ] ] ] .

2.1.11 ResourceSelection

Instances of the ResourceSelection class identify part (described by an oa:Selector) of another resource (referenced with oa:hasSource), possibly from a particular representation of a resource (described by an oa:State). Please note that ResourceSelection is not used directly in the Web Annotation model, but is provided as a separate class for further application profiles to use, separate from oa:SpecificResource which has many Annotation specific features.

Example 11: oa:ResourceSelection
<http://example.org/cell1> a oa:ResourceSelection ;
    oa:hasSource <http://example.org/image1> ;
    oa:hasSelector [
      a oa:XPathSelector ;
      rdfs:value "//table[1]/tr[1]/td[4]" ] .

2.1.12 Selector

A resource which describes the segment of interest in a representation of a Source resource, indicated with oa:hasSelector from the Specific Resource. This class is not used directly in the Annotation model, only its subclasses.

Note: oa:Selector
No example is given. The class should only be used to derive subClasses.

2.1.13 SpecificResource

Instances of the SpecificResource class identify part of another resource (referenced with oa:hasSource), a particular representation of a resource, a resource with styling hints for renders, or any combination of these, as used within an Annotation.

Example 12: oa:SpecificResource
<http://example.org/anno11> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:hasTarget <http://example.org/region1> .

<http://example.org/region1> a oa:SpecificResource ;
    oa:hasSource <http://example.org/image1> .

2.1.14 State

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.

Note: oa:State
No example is given. The class should only be used in further ontologies to derive subclasses.

2.1.15 Style

A Style describes the intended styling of a resource as applied to the particular Annotation, and thus provides the information ndeed to ensure that rendering is consistent across implementations.

Note: oa:Style
No example is given. The class should only be used in further ontologies to derive subclasses.

2.1.16 SvgSelector

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 13: oa:SvgSelector
<http://example.org/anno12> a oa:Annotation ;
    oa:hasBody <http://example.org/road1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/map1> ;
        oa:hasSelector [
            a oa:SvgSelector, oa:EmbeddedContent ;
            oa:text "<svg:svg> ... </svg:svg>" ;
            dc:format "image/svg+xml" ] ] .

2.1.17 TextPositionSelector

The TextPositionSelector 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.

Example 14: oa:TextPositionSelector
<http://example.org/anno13> a oa:Annotation ;
    oa:hasBody <http://example.org/review1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/ebook1> ;
        oa:hasSelector [
            a oa:TextPositionSelector ;
            oa:start 412 ;
            oa:end 795 ] ] .

2.1.18 TextQuoteSelector

The TextQuoteSelector 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.

Example 15: oa:TextQuoteSelector
<http://example.org/anno14> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
            a oa:TextQuoteSelector ;
            oa:exact "anotation" ;
            oa:prefix "this is an " ;
            oa:suffix " that has some" ] ] .

2.1.19 TextualBody

Example 16: oa:TextualBody
<http://example.org/anno15> a oa:Annotation ;
    oa:hasTarget <http://example.org/photo1> ;
    oa:hasBody [
        a oa:TextualBody;
        oa:text "<p>Comment text</p>" ;
        dc:language "en" ;
        dc:format "text/html" ] .

2.1.20 TimeState

A TimeState records the time at which the resource's state 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 17: oa:TimeState
<http://example.org/anno16> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasState [
            a oa:TimeState ;
            oa:cachedSource <http://example.org/copy1> ;
            oa:sourceDate "2015-07-20T13:30:00Z" ] ] .

2.1.21 XPathSelector

An XPathSelector is used to select elements and content within a resource that supports the Document Object Model via a specified XPath value.

  • URI: http://www.w3.org/ns/oa#XPathSelector
  • Sub Class Of: oa:Selector
  • Required Predicates: rdf:value
Example 18: oa:TimeState
<http://example.org/anno17> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
          a oa:XPathSelector ;
          rdfs:value "//div[@id='elem1']" ] ] .

2.2 Properties

annotationService | bodyText | cachedSource | canonical | end | exact | hasBody | hasPurpose | hasScope | hasSelector | hasSource | hasState | hasTarget | motivatedBy | prefix | refinedBy | sourceDate | sourceDateEnd | sourceDateStart | start | styleClass | styledBy | suffix | text | via

2.2.1 annotationService

The object of the relationship is the end point of a service that conforms to the [annotation-protocol], and it may be associated with any resource. The expectation of asserting the relationship is that the object is the preferred service for maintaining annotations about the subject resource, according to the publisher of the relationship.

This relationship is intended to be used both within Linked Data descriptions and as the rel type of a Link, via HTTP Link Headers [rfc5988] for binary resources and in HTML <link> elements. For more information about these, please see the Annotation Protocol specification [annotation-protocol].

  • URI: http://www.w3.org/ns/oa#annotationService
Example 19: oa:annotationService
<http://example.org/diagram.jpg> a dctypes:Image ;
    oa:annotationService <http://example.org/services/annotations/> .

2.2.2 bodyText

The object of the predicate is a plain text string to be used as the content of the body of the Annotation. The value MUST be an xsd:string and that data type MUST NOT be expressed in the serialization. Note that language MUST NOT be associated with the value either as a language tag, as that is only available for rdf:langString.

  • URI: http://www.w3.org/ns/oa#bodyText
  • Domain: oa:Annotation
  • Range: xsd:string
Example 20: oa:bodyText
<http://example.org/anno18> a oa:Annotation ;
    oa:bodyText "Comment text" ;
    oa:hasTarget <http://example.org/target1> .

2.2.3 cachedSource

A object of the relationship is a copy of the Source resource's representation, appropriate for the Annotation.

  • URI: http://www.w3.org/ns/oa#cachedSource
  • Domain: oa:TimeState
Example 21
<http://example.org/anno19> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasState [
            a oa:TimeState ;
            oa:cachedSource <http://example.org/copy1> ;
            oa:sourceDate "2015-07-20T13:30:00Z" ] ] .

2.2.4 canonical

A object of the relationship is the canonical URI that can always be used to deduplicate the Annotation, regardless of the current URI used to access the representation.

  • URI: http://www.w3.org/ns/oa#canonical
Example 22
<http://example.org/anno20> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget <http://example.org/page1> ;
    oa:canonical <urn:uuid:dbfb1861-0ecf-41ad-be94-a584e5c4f1df> .

2.2.5 end

The end property is used to convey the 0-based index of the end position of a range of content.

  • URI: http://www.w3.org/ns/oa#end
  • Range: xsd:integer
Example 23: oa:end
<http://example.org/anno21> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/diskimg1> ;
        oa:hasSelector [
            a oa:DataPositionSelector ;
            oa:start 4096 ;
            oa:end 4104 ] ] .

2.2.6 exact

The object of the predicate is a copy of the text which is being selected, after normalization.

  • URI: http://www.w3.org/ns/oa#exact
  • Range: xsd:string
Example 24: oa:exact
<http://example.org/anno22> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
            a oa:TextQuoteSelector ;
            oa:exact "anotation" ;
            oa:prefix "this is an " ;
            oa:suffix " that has some" ] ] .

2.2.7 hasBody

The object of the relationship is a resource that is a body of the Annotation.

Example 25: oa:hasBody
<http://example.org/anno23> a oa:Annotation ;
    oa:hasBody <http://example.org/post1> ;
    oa:hasTarget <http://example.com/page1> .

2.2.8 hasEndSelector

The relationship between a RangeSelector and the Selector that describes the end position of the range.

Example 26: oa:hasEndSelector
<http://example.org/anno24> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
          a oa:RangeSelector ;
          oa:hasStartSelector [
            a oa:XPathSelector ;
            rdfs:value "//table[1]/tr[1]/td[2]" ] ;
          oa:hasEndSelector [
            a oa:XPathSelector ;
            rdfs:value "//table[1]/tr[1]/td[4]" ] ] ] .

2.2.9 hasPurpose

The purpose served by the resource in the Annotation.

Example 27: oa:hasPurpose
<http://example.org/anno25> a oa:Annotation ;
    oa:motivatedBy oa:bookmarking ;
    oa:hasBody [
        oa:text "readme" ;
        oa:hasPurpose oa:tagging ] ;
    oa:hasTarget <http://example.org/page1> .

2.2.10 hasScope

The scope or context in which the resource is used within the Annotation.

Example 28: oa:hasPurpose
<http://example.org/anno26> a oa:Annotation ;
    oa:motivatedBy oa:bookmarking ;
    oa:hasBody <http://example.org/comment1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/logo1.jpg> ;
        oa:hasScope <http://example.org/index.html> ] .

2.2.11 hasSelector

The object of the relationship is a Selector that describes the segment or region of interest within the source resource. Please note that the domain (oa:ResourceSelection) is not used directly in the Web Annotation model.

Example 29: oa:hasSelector
<http://example.org/anno27> a oa:Annotation ;
    oa:hasBody [
      oa:hasSource <http://example.org/page1> ;
      oa:hasSelector <http://example.org/paraselector1> ] ;
    oa:hasTarget [
      oa:hasSource <http://example.com/dataset1> ;
      oa:hasSelector <http://example.org/dataselector1> ] .

2.2.12 hasSource

The resource that the ResourceSelection, or its subclass SpecificResource, is refined from, or more specific than. Please note that the domain (oa:ResourceSelection) is not used directly in the Web Annotation model.

Example 30: oa:hasSource
<http://example.org/anno28> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:hasTarget <http://example.org/region1> .

<http://example.org/region1> a oa:SpecificResource ;
    oa:hasSource <http://example.org/image1> .

2.2.13 hasStartSelector

The relationship between a RangeSelector and the Selector that describes the start position of the range.

Example 31: oa:hasStartSelector
<http://example.org/anno29> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
          a oa:RangeSelector ;
          oa:hasStartSelector [
            a oa:XPathSelector ;
            rdfs:value "//table[1]/tr[1]/td[2]" ] ;
          oa:hasEndSelector [
            a oa:XPathSelector ;
            rdfs:value "//table[1]/tr[1]/td[4]" ] ] ] .

2.2.14 hasState

The relationship between the ResourceSelection, or its subclass SpecificResource, and a State resource. Please note that the domain (oa:ResourceSelection) is not used directly in the Web Annotation model.

Example 32: oa:hasState
<http://example.org/anno30> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasState <http://example.org/state1> ;
        oa:hasSource <http://example.org/page1> ] .

2.2.15 hasTarget

The relationship between an Annotation and its Target.

Example 33: oa:hasTarget
<http://example.org/anno31> a oa:Annotation ;
    oa:hasBody <http://example.org/post1> ;
    oa:hasTarget <http://example.com/page1> .

2.2.16 motivatedBy

The relationship between an Annotation and a Motivation that describes the reason for the Annotation's creation.

Example 34: oa:motivatedBy
<http://example.org/anno32> a oa:Annotation ;
    oa:hasBody <http://example.org/description1> ;
    oa:hasTarget <http://example.com/resource1> ;
    oa:motivatedBy oa:describing .

2.2.17 prefix

The object of the property is a snippet of content that occurs immediately before the content which is being selected by the Selector.

  • URI: http://www.w3.org/ns/oa#prefix
  • Range: xsd:string
Example 35: oa:prefix
<http://example.org/anno33> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
            a oa:TextQuoteSelector ;
            oa:exact "anotation" ;
            oa:prefix "this is an " ;
            oa:suffix " that has some" ] ] .

2.2.18 refinedBy

The relationship between a Selector or State and another Selector or State that should be applied to the results of the first to refine the processing of the source resource.

  • URI: http://www.w3.org/ns/oa#refinedBy
Example 36: oa:refinedBy
<http://example.org/anno34> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:hasTarget [
        a oa:SpecificResource ;
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
          a oa:FragmentSelector ;
          rdf:value "para5" ;
          oa:refinedBy [
            a oa:TextQuoteSelector ;
            oa:exact "Selected Text" ;
            oa:prefix "text before the " ;
            oa:suffix "and text after it" ] ] ] .

2.2.19 renderedVia

A system that was used by the application that created the Annotation to render the resource.

Example 37: oa:prefix
<http://example.org/anno35> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:hasTarget [
      a oa:SpecificResource ;
      oa:hasSource <http://example.org/page1> ;
      oa:renderedVia [
        a as:Application ;
        schema:softwareVersion "2.5" ] ] .

2.2.20 sourceDate

The timestamp at which the Source resource should be interpreted as being applicable to the Annotation.

  • URI: http://www.w3.org/ns/oa#sourceDate
  • Domain: oa:TimeState
  • Range: xsd:dateTime
Example 38: oa:sourceDate
<http://example.org/anno36> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasState [
            a oa:TimeState ;
            oa:sourceDate "2015-07-20T13:30:00Z" ] ] .

2.2.21 sourceDateEnd

The end timestamp of the interval over which the Source resource should be interpreted as being applicable to the Annotation.

  • URI: http://www.w3.org/ns/oa#sourceDate
  • Domain: oa:TimeState
  • Range: xsd:dateTime
Example 39: oa:sourceDate
<http://example.org/anno37> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasState [
            a oa:TimeState ;
            oa:sourceDateStart "2015-07-20T13:30:00Z" ;
            oa:sourceDateEnd   "2015-07-21T19:45:00Z" ] ] .

2.2.22 sourceDateStart

The start timestamp of the interval over which the Source resource should be interpreted as being applicable to the Annotation.

  • URI: http://www.w3.org/ns/oa#sourceDate
  • Domain: oa:TimeState
  • Range: xsd:dateTime
Example 40: oa:sourceDate
<http://example.org/anno38> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasState [
            a oa:TimeState ;
            oa:sourceDateStart "2015-07-20T13:30:00Z" ;
            oa:sourceDateEnd   "2015-07-21T19:45:00Z" ] ] .

2.2.23 start

The start position in a 0-based index at which a range of content is selected from the data in the source resource.

  • URI: http://www.w3.org/ns/oa#start
  • Range: xsd:integer
Example 41: oa:start
<http://example.org/anno39> a oa:Annotation ;
    oa:hasBody <http://example.org/review1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/ebook1> ;
        oa:hasSelector [
            a oa:TextPositionSelector ;
            oa:start 412 ;
            oa:end 795 ] ] .

2.2.24 styleClass

The name of the class used in the CSS description referenced from the Annotation that should be applied to the Specific Resource.

Example 42: oa:styleClass
<http://example.org/anno40> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:styledBy <http://example.org/style1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/document1> ;
        oa:styleClass "red" ] .

<http://example.org/style1> a oa:CssStyle .

2.2.25 styledBy

A reference to a Stylesheet that should be used to apply styles to the Annotation rendering.

Example 43: oa:styledBy
<http://example.org/anno41> a oa:Annotation ;
    oa:hasBody <http://example.org/body1> ;
    oa:styledBy [
        a oa:CssStyle, oa:EmbeddedContent ;
        dc:format "text/css" ;
        rdf:value ".red { color: red }" ] ;
    oa:hasTarget [
        oa:hasSource <http://example.org/target1> ;
        oa:styleClass "red" ] .

2.2.26 suffix

The snippet of text that occurs immediately after the text which is being selected.

  • URI: http://www.w3.org/ns/oa#suffix
  • Range: xsd:string
Example 44: oa:suffix
<http://example.org/anno42> a oa:Annotation ;
    oa:hasBody <http://example.org/comment1> ;
    oa:hasTarget [
        oa:hasSource <http://example.org/page1> ;
        oa:hasSelector [
            a oa:TextQuoteSelector ;
            oa:exact "anotation" ;
            oa:prefix "this is an " ;
            oa:suffix " that has some" ] ] .

2.2.27 text

The content of a resource, given as text.

  • URI: http://www.w3.org/ns/oa#text
  • Domain: oa:Content
  • Range: xsd:string
Example 45: oa:text
<http://example.org/anno43> a oa:Annotation ;
    oa:hasTarget <http://example.org/photo1> ;
    oa:hasBody [
        a oa:TextualBody;
        oa:text "<p>Comment text</p>" ;
        dc:language "en" ;
        dc:format "text/html" ] .

2.2.28 via

A object of the relationship is a resource from which the source resource was retrieved by the providing system.

  • URI: http://www.w3.org/ns/oa#via
Example 46
<http://example.org/anno44> a oa:Annotation ;
    oa:hasBody <http://example.org/note1> ;
    oa:hasTarget <http://example.org/page1> ;
    oa:via <http://other.example.com/anno1b> .

2.3 Named Individuals

2.3.1 bookmarking

The motivation for when the user intends to create a bookmark to the Target or part thereof.

  • URI: http://www.w3.org/ns/oa#bookmarking
Example 47: oa:bookmarking
<http://example.org/anno45> a oa:Annotation ;
    oa:hasTarget <http://example.com/page1> ;
    oa:motivatedBy oa:bookmarking .

2.3.2 classifying

The motivation for when the user intends to that classify the Target as something.

  • URI: http://www.w3.org/ns/oa#classifying
Example 48: oa:classifying
<http://example.org/anno46> a oa:Annotation ;
    oa:hasBody <http://example.org/type1> ;
    oa:hasTarget <http://example.com/resource1> ;
    oa:motivatedBy oa:classifying .

2.3.3 commenting

The motivation for when the user intends to comment about the Target.

  • URI: http://www.w3.org/ns/oa#commenting
Example 49: oa:commenting
<http://example.org/anno47> a oa:Annotation ;
    oa:hasBody [ oa:text "A comment about the page" ] ;
    oa:hasTarget <http://example.com/page1> ;
    oa:motivatedBy oa:commenting .

2.3.4 describing

The motivation for when the user intends to describe the Target, as opposed to a comment about them.

  • URI: http://www.w3.org/ns/oa#describing
Example 50: oa:describing
<http://example.org/anno48> a oa:Annotation ;
    oa:hasBody [ oa:text "A description of the image" ] ;
    oa:hasTarget <http://example.com/image1> ;
    oa:motivatedBy oa:describing .

2.3.5 editing

The motivation for when the user intends to request a change or edit to the Target resource.

  • URI: http://www.w3.org/ns/oa#editing
Example 51: oa:editing
<http://example.org/anno49> a oa:Annotation ;
    oa:hasBody [ oa:text "Editorial suggestion" ] ;
    oa:hasTarget <http://example.com/text1> ;
    oa:motivatedBy oa:editing .

2.3.6 highlighting

The motivation for when the user intends to highlight the Target resource or segment of it.

  • URI: http://www.w3.org/ns/oa#highlighting
Example 52: oa:highlighting
<http://example.org/anno50> a oa:Annotation ;
    oa:hasTarget <http://example.com/region1> ;
    oa:motivatedBy oa:highlighting .

2.3.7 identifying

The motivation for when the user intends to assign an identity to the Target or identify what is being depicted or described in the Target.

  • URI: http://www.w3.org/ns/oa#identifying
Example 53: oa:identifying
<http://example.org/anno51> a oa:Annotation ;
    oa:hasBody <http://example.com/identities/object1> ;
    oa:hasTarget <http://example.com/image-of-object1> ;
    oa:motivatedBy oa:identifying .

2.3.8 linking

The motivation for when the user intends to link to a resource related to the Target.

  • URI: http://www.w3.org/ns/oa#linking
Example 54: oa:linking
<http://example.org/anno52> a oa:Annotation ;
    oa:hasBody <http://example.org/from1> ;
    oa:hasTarget <http://example.com/to1> ;
    oa:motivatedBy oa:linking .

2.3.9 moderating

The motivation for when the user intends to assign some value or quality to the Target.

  • URI: http://www.w3.org/ns/oa#moderating
Example 55: oa:moderating
<http://example.org/anno53> a oa:Annotation ;
    oa:hasBody <http://example.org/tags/approved1> ;
    oa:hasTarget <http://example.com/anno1> ;
    oa:motivatedBy oa:moderating .

2.3.10 questioning

The motivation for when the user intends to ask a question about the Target.

  • URI: http://www.w3.org/ns/oa#questioning
Example 56: oa:questioning
<http://example.org/anno54> a oa:Annotation ;
    oa:hasBody [ oa:text "A question about the resource" ] ;
    oa:hasTarget <http://example.com/resource1> ;
    oa:motivatedBy oa:questioning .

2.3.11 replying

The motivation for when the user intends to reply to a previous statement, either an Annotation or another resource.

  • URI: http://www.w3.org/ns/oa#replying
Example 57: oa:replying
<http://example.org/anno55> a oa:Annotation ;
    oa:hasBody [ oa:text "A reply to a question" ] ;
    oa:hasTarget <http://example.com/anno1> ;
    oa:motivatedBy oa:replying .

2.3.12 reviewing

The motivation for when the user intends to review the Target in some assessing fashion, rather than simply make a comment about it.

  • URI: http://www.w3.org/ns/oa#reviewing
Example 58: oa:reviewing
<http://example.org/anno56> a oa:Annotation ;
    oa:hasBody [ oa:text "A review of the resource" ] ;
    oa:hasTarget <http://example.com/resource1> ;
    oa:motivatedBy oa:reviewing .

2.3.13 tagging

The motivation for when the user intends to associate a tag with the Target.

  • URI: http://www.w3.org/ns/oa#tagging
Example 59: oa:tagging
<http://example.org/anno57> a oa:Annotation ;
    oa:hasBody [ oa:text "tag" ] ;
    oa:hasTarget <http://example.com/thing1> ;
    oa:motivatedBy oa:tagging .

4. Extensions

This vocabulary may be extended in the regular way, by creating new or importing existing predicates and classes from other RDF based ontologies. Extensions may be made to any resource, including adding new objects as well as properties. If there is a property in one of the ontologies that are already included in the context, then it is RECOMMENDED to use a CURIE, the namespace and property name separated by a : character, as the JSON-LD key rather than creating a new context.

For example, it is easier to add skos:prefLabel to the Annotation rather than requiring clients to download a new context document to discover the mapping.

Example 97: Extension Example 1
{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "http://example.org/anno77",
  "type": "Annotation",
  "skos:prefLabel": "Picture Annotation",
  "body": {
    "type": "TextualBody",
    "value": "I love this picture!"
  },
  "target": {
    "id": "http://example.com/images/picture1",
    "type": "Image"
  }
}

In order to ensure a lack of collision between key names, a JSON-LD context document SHOULD be made available when the term is not from an ontology that is already in the Web Annotation context. Extension contexts MUST NOT redefine existing JSON-LD keys from the Web Annotation context. Implementations MUST ignore unfamiliar properties when processing the data, but servers SHOULD preserve them if they are part of a valid and included context.

For example, adding height and width for images from the EXIF vocabulary [exif] could be done by defining a JSON-LD context, and including the height and width properties and linking to the newly defined context in the Annotation's serialization.

Example 98: Extension Example 2
{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "http://example.org/images/ns/extension.jsonld"
  ],
  "id": "http://example.org/anno78",
  "type": "Annotation",
  "skos:prefLabel": "Picture Annotation",
  "body": {
    "type": "TextualBody",
    "value": "I love this picture!"
  },
  "target": {
    "id": "http://example.com/images/picture1",
    "type": "Image",
    "height": 768,
    "width": 1024
  }
}

Note that the current JSON-LD [JSON-LD] specification does not allow arrays to contain other arrays directly. As JSON-LD is the RECOMMENDED serialization format, extensions SHOULD avoid the use of this pattern.

A. JSON-LD Context

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. The same URI SHOULD be used as the profile URI for representations that conform to the model and context.

{
 "@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#",
    "iana":    "http://www.iana.org/assignments/relation/",
    "owl":     "http://www.w3.org/2002/07/owl#",
    "as":      "http://www.w3.org/ns/activitystreams#",
    "schema":  "http://schema.org/",

    "id":      {"@type": "@id", "@id": "@id"},
    "type":    {"@type": "@id", "@id": "@type"},

    "Annotation":           "oa:Annotation",
    "Dataset":              "dctypes:Dataset",
    "Image":                "dctypes:StillImage",
    "Video":                "dctypes:MovingImage",
    "Audio":                "dctypes:Sound",
    "Text":                 "dctypes:Text",
    "Content":              "oa:Content",
    "TextualBody":          "oa:TextualBody",
    "ResourceSelection":    "oa:ResourceSelection",
    "SpecificResource":     "oa:SpecificResource",
    "FragmentSelector":     "oa:FragmentSelector",
    "CssSelector":          "oa:CssSelector",
    "XPathSelector":        "oa:XPathSelector",
    "TextQuoteSelector":    "oa:TextQuoteSelector",
    "TextPositionSelector": "oa:TextPositionSelector",
    "DataPositionSelector": "oa:DataPositionSelector",
    "SvgSelector":          "oa:SvgSelector",
    "RangeSelector":        "oa:RangeSelector",
    "TimeState":            "oa:TimeState",
    "HttpState":            "oa:HttpRequestState",
    "CssStylesheet":        "oa:CssStyle",
    "Choice":               "oa:Choice",
    "Person":               "foaf:Person",
    "Software":             "as:Application",
    "Organization":         "foaf:Organization",
    "AnnotationCollection": "as:OrderedCollection",
    "AnnotationPage":       "as:OrderedCollectionPage",
    "Audience":             "schema:Audience",

    "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":          {"@type": "@id", "@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"},
    "refinedBy":     {"@type": "@id", "@id": "oa:refinedBy"},
    "startSelector": {"@type": "@id", "@id": "oa:hasStartSelector"},
    "endSelector":   {"@type": "@id", "@id": "oa:hasEndSelector"},
    "renderedVia":   {"@type": "@id", "@id": "oa:renderedVia"},
    "creator":       {"@type": "@id", "@id": "dcterms:creator"},
    "generator":     {"@type": "@id", "@id": "as:generator"},
    "rights":        {"@type": "@id", "@id": "dcterms:rights"},
    "motivation":    {"@type": "@vocab", "@id": "oa:motivatedBy"},
    "purpose":       {"@type": "@vocab", "@id": "oa:hasPurpose"},
    "homepage":      {"@type": "@id", "@id": "foaf:homepage"},
    "via":           {"@type": "@id", "@id": "oa:via"},
    "canonical":     {"@type": "@id", "@id": "oa:canonical"},
    "stylesheet":    {"@type": "@id", "@id": "oa:styledBy"},
    "cached":        {"@type": "@id", "@id": "oa:cachedSource"},
    "conformsTo":    {"@type": "@id", "@id": "dcterms:conformsTo"},
    "items":         {"@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"},
    "audience":      {"@type": "@id", "@id": "schema:audience"},

    "bodyText":      "oa:bodyText",
    "format":        "dc:format",
    "language":      "dc:language",
    "created":       "dcterms:created",
    "modified":      "dcterms:modified",
    "generated":     "dcterms:issued",
    "text":          "oa:text",
    "value":         "rdf:value",
    "start":         "oa:start",
    "end":           "oa:end",
    "exact":         "oa:exact",
    "prefix":        "oa:prefix",
    "suffix":        "oa:suffix",
    "sourceDate":    "oa:sourceDate",
    "sourceDateStart": "oa:sourceDateStart",
    "sourceDateEnd": "oa:sourceDateEnd",
    "styleClass":    "oa:styleClass",
    "name":          "foaf:name",
    "email":         "foaf:mbox",
    "email_sha1":    "foaf:mbox_sha1sum",
    "account":       "foaf:nick",
    "label":         "rdfs:label",
    "total":         "as:totalItems",
    "startIndex":    "as:startIndex"
  }
}

B. JSON-LD Frames

There is an unofficial, yet well implemented, JSON-LD specification [json-ld-framing] that describes a deterministic layout for serializing an RDF graph into a particular JSON-LD document layout. Applying the following frames to the graph of information will generate JSON as close as possible to the serialization recommended by the Web Annotation Data Model.

B.1 Annotation Frame

A Frame for serializing a single Annotation.

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "@omitDefault": true,
  "type": "Annotation",
  "via": {"@embed": false},
  "canonical": {"@embed": false},
  "rights": {"@embed": false},
  "motivation": {"@embed": false},
  "body": {"@embed": true},
  "target": {"@embed": true},
  "creator": {"@embed": true},
  "generator": {"@embed": true},
  "audience": {"@embed": true}
}

B.2 Annotation Collection Frame

A Frame for serializing a Collection of Annotations.

{
    "@context" : [
    	"http://www.w3.org/ns/anno.jsonld",
    	"http://www.w3.org/ns/ldp.jsonld"
  	],
    "type": "Collection",
    "first": [{"@embed": "False"}],
    "last": [{"@embed": "False"}]
}
Note
If it is instead desirable to embed the first page of the Collection, change the false for first to true.

B.3 Annotation Page Frame

A Frame for serializing a Page from a Collection of Annotations.

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "@omitDefault": true,
  "type": "AnnotationPage",
  "next": {"@embed": false},
  "prev": {"@embed": false},
  "partOf": {"@embed": false},
  "items": {"@embed": true}
}

C. 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

Use of SKOS to extend motivations
Fig. 1 Extending Motivations

D. 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.

The following people have been instrumental in providing thoughts, feedback, reviews, content, criticism and input in the creation of this specification:

Vladimir Alexiev, Art Barstow, Tim Berners-Lee, Chris Birk, Dan Brickley, Sarven Capadisli, Paolo Ciccarese, Tim Cole, Ray Denenberg, TB Dinesh, Sergiu Gordea, Benjamin Goering, Amy Guy, Ivan Herman, Frederick Hirsch, Antoine Isaac, Jacob Jett, Takeshi Kanai, Gregg Kellogg, Andreas Kuckartz, Randall Leeds, Hugo Manguinhas, Ben De Meester, Luc Moreau, Addison Phillips, Davis Salisbury, Robert Sanderson, Felix Sasaki, Doug Schepers, Tzviya Siegman, Stian Soiland-Reyes, Manu Sporney, Nick Stenning, Jon Stroop, Lutz Suhrbier, Kyrce Swenson, Raphael Troncy, Simeon Warner, Erik Wilde, Dan Whaley, Benjamin Young

E. References

E.1 Normative references

[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 project. FOAF Vocabulary Specification 0.99 (Paddington Edition). 14 January 2014. URL: http://xmlns.com/foaf/spec
[JSON-LD]
Manu Sporny; Gregg Kellogg; Markus Lanthaler. W3C. JSON-LD 1.0. 16 January 2014. W3C Recommendation. URL: http://www.w3.org/TR/json-ld/
[RFC2119]
S. Bradner. IETF. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[Turtle]
Eric Prud'hommeaux; Gavin Carothers. W3C. RDF 1.1 Turtle. 25 February 2014. W3C Recommendation. URL: http://www.w3.org/TR/turtle/
[activitystreams-vocabulary]
James Snell; Evan Prodromou. W3C. Activity Vocabulary. 15 December 2015. W3C Working Draft. URL: http://www.w3.org/TR/activitystreams-vocabulary/
[web-annotation]
Robert Sanderson; Paolo Ciccarese; Benjamin Young. W3C. Web Annotation Data Model. 31 March 2016. W3C Working Draft. URL: http://www.w3.org/TR/2016/WD-annotation-model-20160331/
[annotation-protocol]
Robert Sanderson. W3C. Web Annotation Protocol. 31 March 2016. W3C Working Draft. URL: http://www.w3.org/TR/2016/WD-annotation-protocol-20160331/
[rdf-schema]
Dan Brickley; Ramanathan Guha. W3C. RDF Schema 1.1. 25 February 2014. W3C Recommendation. URL: http://www.w3.org/TR/rdf-schema/
[rfc5988]
M. Nottingham. IETF. Web Linking. October 2010. Proposed Standard. URL: https://tools.ietf.org/html/rfc5988
[skos-reference]
Alistair Miles; Sean Bechhofer. W3C. SKOS Simple Knowledge Organization System Reference. 18 August 2009. W3C Recommendation. URL: http://www.w3.org/TR/skos-reference
[xmlschema-2]
Paul V. Biron; Ashok Malhotra. W3C. XML Schema Part 2: Datatypes Second Edition. 28 October 2004. W3C Recommendation. URL: http://www.w3.org/TR/xmlschema-2/

E.2 Informative references

[exif]
W3C. Exif Vocabulary Workspace - RDF Schema. URL: https://www.w3.org/2003/12/exif/
[json-ld-framing]
W3C JSON-LD Community Group. JSON-LD Framing 1.0. URL: http://json-ld.org/spec/latest/json-ld-framing/