This version:
http://www.openannotation.org/spec/core/20120509/index.html
Latest version:
http://www.openannotation.org/spec/core/
Previous version:
http://www.openannotation.org/spec/core/20120501.html
Authors, Editors:
Robert Sanderson, Los Alamos National Laboratory
Paolo Ciccarese, Massachusetts General Hospital and Harvard Medical School
Herbert Van de Sompel, Los Alamos National Laboratory
Authors:
Tim Clark, Massachusetts General Hospital and Harvard Medical School
Tim Cole, University of Illinois at Urbana-Champaign
Jane Hunter, University of Queensland
Neil Fraistat, University of Maryland

Abstract

The Open Annotation Core Data Model specifies an interoperable framework for creating associations between related resources, annotations, using a methodology which conforms to the Architecture of the World Wide Web. Open Annotations 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, including a body and target, and conveys that the body is somehow about the target. The full model supports additional functionality, enabling semantic tagging, embedding content, selecting segments of resources, choosing the appropriate representation of a resource and providing styling hints for consuming clients.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

Copyright © 2012 the Contributors to the Open Annotation Core Data Model Specification, published by the Open Annotation Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

This specification was published by the Open Annotation Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

This document has been made available to the Open Annotation Community Group for review, but is not endorsed by them. This is a working draft, and it is not endorsed by the W3C or its members. It is inappropriate to refer to this document other than as "work in progress".

Please send general comments about this document to the public mailing list: public-openannotation@w3.org (public archives).


Table of Contents

  1. Introduction
    1. Namespaces
    2. Terminology
    3. Examples
  2. Annotation
    1. Body and Target
    2. Provenance
    3. Classes of Annotation
    4. Serialization
  3. Body
    1. Body Resource
    2. Annotations without a Body
    3. Inline Body
    4. Specific Body
  4. Target
    1. Target Resource
    2. Multiple Targets
    3. Inline Target
    4. Specific Target
  5. Specifier
    1. State
    2. Selector
      1. Fragment Selector
    3. Style
    4. Alternative Specifiers
    5. Inline Specifiers
  6. Inline Resources
    1. Inline Body
    2. Inline Target
    3. Inline Specifier
    4. Publishing Inline Resources
  7. Summary
  8. Appendices
    1. References
    2. Acknowledgements
    3. Change Log

1. Introduction

Annotating, the act of creating associations between distinct pieces of information, is a pervasive activity online in many guises but lacks a structured approach. 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 photos on Flickr, videos on YouTube, people's posts on Facebook, or mentions of resources on Twitter could all be considered as annotations associated with the resource being discussed. In addition, there a plethora of closed and proprietary web-based "sticky note" systems, and stand-alone multimedia annotation systems. The primary complaint about all of these systems is that the user created annotations cannot be shared or reused, due to a deliberate "lock-in" strategy within the environments where they were created, or at the very least the lack of a common approach to expressing the annotations.

The Open 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, including a body and target, and conveys that the body is somehow about the target. This perspective results in a basic model with three parts, depicted below. The full model supports additional functionality, enabling semantic tagging, embedding content, selecting segments of resources, choosing the appropriate representation of a resource and providing styling hints for consuming clients. Annotations created by or intended for machines are also considered to be in scope, ensuring that the Data Web is not ignored in favor of only considering the human-oriented Document Web.


Figure 1. Annotation, Body and Target

Unlike previous attempts at annotation interoperability, the Open Annotation system does not prescribe a protocol for creating, managing and retrieving annotations. Instead it describes a web-centric method, promoting discovery and sharing of annotations without clients or servers having to agree on a particular set of operations on those annotations.

1.1 Namespaces

The Open Annotation model defines two namespaces:

The Core ontology is intended to be static and will always use the same Namespace URI. The Extension ontology is intended to be more fluid, enabling responsiveness to community requirements without jeopardizing the core of the model. Before creating private extensions, communities should check the Extension documentation to see if their requirements have already been accounted for. Also, if communities feel that their extension can be generally useful, then it should be discussed for inclusion within the Extension namespace.

The Core and Extension Namespace URIs will always remain the same, even if the ontology changes. All versions of the ontologies will remain available from version specific URLs, and the namespace URI will provide access to the most recent version.

The following namespaces are used in this document:

PrefixNamespaceDescription
oahttp://www.w3.org/ns/openannotation/core/ The core Open Annotation model
oaxhttp://www.w3.org/ns/openannotation/extension/ Interoperable extensions to the core model
cnthttp://www.w3.org/2011/content#Representing Content in RDF
dchttp://purl.org/dc/elements/1.1/Dublin Core Elements
dctermshttp://purl.org/dc/terms/Dublin Core Terms
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#RDF

1.2 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 RFC 2119.

1.3 Examples

Examples used throughout the document will be conveyed as both a diagram and in the Turtle RDF format, and do not represent specific use cases with real resources. The Turtle examples do not provide namespace declarations, and should be considered to follow the Namespaces table in Section 1.1. Usage examples in SPARQL are given for each section, based on a requirement expressed in natural language. Additional examples of how to model and implement specific situations are available in the Annotation Cookbook.

The diagrams in the specification use the following style:

2. Annotation

An Annotation is the expression, in the form of a serialized graph, of a relationship between two or more resources. This section explains how to identify the related resources, how to provide information concerning the creation and intent of the Annotation, and describes options for serializing the graph.

2.1 Body and Target

Typically, an Annotation has a single Body resource, and a single Target resource, that the Body is somehow "about". This "aboutness" may be further clarified, as discussed in the subsection on Classes of Annotation. The Body and Target may be of any media type, and contain any type of content. The Body and Target are typically identified by HTTP URIs. Please see the dedicated sections on Body and Target for more information about these resources.

The model defines two relationships, oa:hasBody and oa:hasTarget, to associate the Body and Target resources with the Annotation respectively. The model does not define classes for Body and Target, as the Body of one Annotation may be the Target of another, and thus the class is not globally correct. The oa:hasBody and oa:hasTarget relationships should thus be used in queries to match Body and Target.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:AnnotationClassThe class for Annotations
oa:hasBodyRelationshipThe relationship between an Annotation and the Body of the Annotation. See the section on Bodies for more detail.
oa:hasTargetRelationshipThe relationship between an Annotation and the Target of the Annotation. See the section on Targets for more detail.
Basic Annotation Model:

Figure 2.1. Basic Model
 <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <Target1> .

Usage

Requirement: Find the annotations that reference a particular target:
   SELECT ?anno WHERE { ?anno oa:hasTarget <Target1> }
=> <Anno1>
Requirement: Find all of the resources which are about a particular target:
   SELECT ?body WHERE { ?anno oa:hasBody ?body . ?anno oa:hasTarget <Target1> }
=> <Body1>

See Example List

2.2 Provenance

It is important for consuming clients and services to understand the context in which the Annotation was created. In particular, the person or machine, such as named entity recognition software annotating text with references to the identities of the entities it discovers, responsible for the Annotation (the oa:annotator) deserves credit for their contribution, and the time at which the Annotation was created is useful information for filtering out old, potentially irrelevant annotations. The version of the Open Annotation model that was used to express the Annotation is important to know, as semantics or requirements may have changed over time. Finally, the software that generated the serialization is potentially useful to know, for example if there was a bug in a particular version or simply as annotation client advertising.

It is important to note that the provenance information applies only to the Annotation, and not necessarily the Body, Target or any other resource. Provenance information may be attached to those, and other, resources as appropriate.

This model does not specify anything further about properties of the agents involved in the provenance of the Annotation. Different communities will have different requirements, especially when describing the different roles of software and human agents involved in the creation of the Annotation. Implementors of the model should use the most common, existing ontologies available to describe the entities involved.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:annotatorRelationship [subProperty of dcterms:creator] The object of the relationship is a resource that identifies the agent responsible for asserting the triples in the Annotation graph. This may be either a human or software agent.
There SHOULD be exactly 1 oa:annotator relationship per Annotation, but MAY be 0 or more, as the Annotation may be anonymous, or multiple agents may have worked together on it.
oa:annotatedProperty[subProperty of dcterms:created] The time at which the oa:annotator created the Annotation.
There SHOULD be exactly 1 oa:annotated property per Annotation, and SHOULD NOT be more than 1.
oa:generatorRelationship[subProperty of dcterms:publisher] The object of the relationship is the agent, likely software, responsible for generating the serialization of the Annotation's graph.
There MAY be 0 or more oa:generator relationships per Annotation.
oa:generatedProperty[subProperty of dcterms:issued] The time at which the agent referenced by oa:generator generated the first serialization of the Annotation graph, and any subsequent substantially different one. The graph MUST have changed for this property to be updated, and as such represents the last modified datestamp for the graph. This might be used to determine if the graph should be re-imported into a triplestore when discovered.
There MAY be exactly 1 oa:generated property per Annotation, and SHOULD NOT be more than 1.
oa:modelVersionRelationshipThe version of the model that was used for the Annotation. The object of the relationship is an RDF ontology describing the version of the Open Annotation Core namespace used. The Open Annotation namespace itself does not change, and hence this is not sufficient information to determine which version of the model is being used.
There SHOULD be exactly 1 oa:modelVersion relationship per Annotation. If oa:modelVersion is not present, then there MUST be some alternative means of determining the model in use.
Annotation Provenance Model:

Figure 2.2. Annotation Provenance
 <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <Target1> ;
    oa:annotator <Agent1> ;
    oa:annotated "datetime1" ;
    oa:generator <Agent2> ;
    oa:generated "datetime2" ;
    oa:modelVersion <Version1> .

Usage

Requirement: Find all of the annotations written by a particular person, about a given resource.
   SELECT ?anno WHERE { ?anno oa:hasTarget <Target1> . ?anno oa:annotator <Agent1> }
=> <Anno1>
Requirement: Find all of the annotations which were produced using a particular version of the model.
   SELECT ?anno WHERE { ?anno oa:modelVersion <Version1> }
=> <Anno1>

See Example List

2.3 Classes of Annotation

In many cases it is important to understand the reasons why the Annotation was created. Open Annotation uses subClasses of the oa:Annotation class to model these reasons, and example instances of it might include Comment, Moderation, Reply, or Link. Cross-community classes are included in the Open Annotation Extension namespace, and communities may define their own. It is RECOMMENDED that if the class does not come from the Open Annotation Extension namespace, then the oa:Annotation class be explicitly provided in addition to ensure that consuming clients are aware that it is an Open Annotation.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
rdf:typeRelationshipThe relationship used between the Annotation and the motivation for its creation, expressed as a subClass of oa:Annotation. An Annotation MAY have other classes which are not subclasses of oa:Annotation and are thus not motivations for the Annotation's creation.
There MUST be 1 or more rdf:type relationships expressed per Annotation
Annotation Class Model:

Figure 2.3. Classes of Annotation
 <Anno1> a oa:Annotation ;
	 a <Class1> ;
    oa:hasBody <Body1> ;
    oa:hasTarget <Target1> .

Usage

Requirement: Find the annotations that were created for a particular reason.
   SELECT ?anno WHERE { ?anno rdf:type <Class1> }
=> <Anno1>

See Example List

2.4 Serialization

The serialization of the Annotation may be in any format capable of expressing the Annotation's graph. It may be embedded within other resources, such as using RDFa to embed the annotation within a web page. It is RECOMMENDED that RDF/XML is used as a default serialization for interoperability purposes.

If the Annotation has an HTTP URI, then when that URI is dereferenced, the Annotation's serialized graph, and only the graph, MUST be returned in an appropriate graph serialization format. When the serialization is embedded within other resources, such as when expressed in RDFa, this HTTP URI MUST continue to be expressed in the serialization.

If the Annotation is not available from any other dereferencable URI, but only embedded within a containing resource, then it MUST have a globally unique URN identifer such as a UUID or tag URI.

If a system retrieves and republishes an Annotation at a different HTTP URI, then it SHOULD express the oa:equivalent relationship between the Annotation's identifier and the new one it just generated. The system then SHOULD update the oa:generated property, as the graph has changed by adding the oa:equivalent relationship. This modified oa:generated property means that owl:sameAs is not appropriate for use in this scenario. As other embedded resources SHOULD also be given HTTP URIs, it is possible for the graph to change significantly, however the content MUST all be reliably and consistently available. The publishing system SHOULD honor content negotiation to request different serializations of the Annotation.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:equivalentRelationshipThe subject and object resources of the oa:equivalent relationship represent the same Annotation, but potentially have different metadata such as generator, generated and serialization format. oa:equivalent is a symmetrical relationship; if A oa:equivalent B, then it is also true that B oa:equivalent A.
The Annotation MAY include 0 or more instances of the oa:equivalent relationship between copies of the Annotation, and SHOULD include as many as are available.
Annotation Serialization Model:

Figure 2.4. Serialization
 <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <Target1> ;
    oa:generated "datetime1" ;
    oa:equivalent <Anno2> .
    
  <Anno2> oa:generated "datetime2" .

Usage

Requirement: Find all of the other identities assigned to an annotation.
   SELECT ?anno WHERE { { ?anno oa:equivalent <Anno1> } UNION { <Anno1> oa:equivalent ?anno } }
=> <Anno2>

See Example List

3. Body

The Body of an Annotation is the comment or other resource which is somehow about the Target, or Targets. It contains the information which is annotating the Target, or Targets. Some Annotations may not have a Body, if they are simply markers of a region or location. In this section we discuss the different types of Body that may be present in an Annotation.

3.1 Body Resource

The Body may be a resource with its own dereferencable URI. When retrieved, it may be of any content type, including structured data intended for machines, not just plain text. The Body resource does not have to have a representation, it may be a non-information resource. The resolution of the Body's URI to retrieve a representation may require multiple steps, including HTTP redirects, and potentially multiple protocols.

The model does not define a Body class, as the same resource may be both the Body of one Annotation and play a different role in another. As such, the class is not reliable or valuable information.

On the other hand, the basic type of the resource is very useful, such as if it is an Image, Text or Video. This information prevents the need for classes of Annotation based on the type of the Body. The class SHOULD be drawn from existing, well known ontologies and is the subject of best-practice recommendations outside of this specification.

Secondly, the exact mime type of the Body's representation, if it has one, is also useful for consuming clients to understand if they can or should retrieve and attempt to process the resource.

An Annotation MUST NOT have more than one Body, as the semantics of the Annotation would become unclear to the point where it is no longer useful. An Annotation is a resource that associates one Body resource with one or more Target resources, and thus if there were multiple Bodies and multiple Targets, it would be impossible to tell which Body was associated with which Target or Targets. It would simply be a collection of somehow related resources, not an Annotation as it is typically understood.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
rdf:typeRelationshipThe relationship between the Body and its class. At least one class SHOULD convey the general format type, such as Video or Audio.
There SHOULD be 1 or more types per Body.
oa:hasBodyRelationshipThe relationship between an Annotation and the Body of the Annotation.
There SHOULD be exactly 1 oa:hasBody relationship, but MAY be 0 (see the next sub-section for more information about this case). There MUST NOT be more than 1 oa:hasBody relationship per Annotation.
dc:formatPropertyThis property conveys the mime type of the resource's representation, if it has one.
There MAY be 0 or more dc:format properties per Body. If there are more than one, then it implies that content negotiation is available for the resource.
Basic Body Model:

Figure 3.1. Annotation Body
 <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <Target1> .

  <Body1> a <Type1> ;
      dc:format "mimetype1" .

Usage

Requirement: Find all of the resources which are about a particular target resource.
   SELECT ?body WHERE { ?anno oa:hasBody ?body . ?anno oa:hasTarget <Target1> }
=> <Body1>

See Example List

3.2 Annotations without a Body

A special case of Annotations is when there is no Body. Examples for this special case include bookmarking a particular resource, or marking a point within a resource, and highlighting a section of a resource without making a comment about why it is highlighted. A Body may be added to these Annotations later, perhaps explaining the importance of the resource and thus why it was bookmarked.

No new relationships or classes are introduced for bodyless Annotations. A motivating class SHOULD be given for why the Annotation was created without a Body.

Model

Bodyless Model:

Figure 3.2. Annotations without a Body
 <Anno1> a oa:Annotation ;
	 a <Class1> ;
    oa:hasTarget <Target1> .

Usage

Requirement: Find all of the bodyless annotations created for a given reason on a known target resource.
 SELECT ?anno
  WHERE { ?anno oa:hasTarget <Target1> ; rdf:type <Class1> .
    FILTER(NOT EXISTS { ?anno oa:hasBody ?notbody })
  } 
=> <Anno1>

Please note that this example uses features from SPARQL version 1.1.

See Example List

3.3 Inline Body

It is possible to embed the representation of the Body resource within the Annotation graph. This enables clients to submit a single serialization to a service, rather than one for the Annotation and a second for the Body. This is discussed in detail in the Inline Body.

3.4 Specific Body

It is possible for the Body to be a particular representation of a resource, or part of such a representation, rather than simply whatever is retrieved when dereferencing the the resource's URI when the Annotation is being processed.

This Specific Body identifies the exact combination of the full, unqualified resource plus any Specifiers (State, Selector and Style) that describe how it should be refined. The identity of the Specific Body is the target of the oa:hasBody relationship, and the full resource, the Source, is referenced from it by oa:hasSource. The Specific Body is typically identified by a URN, as an HTTP URI would imply that the exact nature of the Specific Body was available to retrieve by dereferencing the HTTP URI. The Specific Body MAY be used by multiple Annotations, but it must be understood that it is the exact combination of all of the Specifiers applied to the Source resource.

The description of exactly how to determine the representation is discussed in detail in the Specifiers section.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:SpecificResourceClassA resource which identifies part of another resource, a particular representation of a resource, a resource with styling hints for renders, or any combination of these.
oa:hasSourceRelationshipThe relationship between a oa:SpecificResource and the resource that it is a more specific representation of.
There MUST be exactly 1 oa:hasSource relationship per oa:SpecificResource instance.
Specific Body Model:

Figure 3.4. Specific Body
 <Anno1> a oa:Annotation ;
    oa:hasBody <SpBody1> ;
    oa:hasTarget <Target1> .
    
  <SpBody1> a oa:SpecificResource ;
    oa:hasSource <Body1> .

Usage

Requirement: Find all of the annotations in which a given resource, or part of it, are the body of the annotation.
   SELECT ?anno WHERE { { ?anno oa:hasBody <Body1> } UNION { ?anno oa:hasBody ?spbody . 
        ?spbody a oa:SpecificResource . ?body oa:hasSource <Body1> }
=> <Anno1>

See Example List

4. Target

The Target of an Annotation is the resource which the Body is somehow about, the resource that is being annotated. An Annotation may have multiple Targets, and each may be a Specific Resource such as part of another resource or a particular representation of a resource.

4.1 Target Resource

The Target may be a resource with its own dereferencable URI. The representation that is retrieved may be of any content type. The resolution of the Target's URI to retrieve a representation may require multiple steps, such as HTTP redirects, and potentially multiple protocols.

The model does not define a Target class, as the same resource may be both the Target of one Annotation and play a different role in another. As such, the class is not reliable or valuable information.

On the other hand, the basic type of the resource is very useful, such as if it is an Image, Text or Video. This information prevents the need for classes of Annotation based on the type of the Target. The class SHOULD be drawn from existing, well known ontologies and is the subject of best-practice recommendations outside of this specification.

The exact mime type of the Target's representation is also useful for consuming clients to understand if they can or should retrieve and attempt to process the resource.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
rdf:typeRelationshipThe relationship between the Target and its class. At least one class SHOULD convey the general format type, such as Video or Audio.
There SHOULD be 1 or more types per Target.
oa:hasTargetRelationshipThe relationship between an Annotation and the Target of the Annotation.
There MUST be 1 oa:hasTarget relationship, and there MAY be more than 1.
dc:formatPropertyThis property conveys the mime type of the resource's representation, if it has one.
There MAY be 0 or more dc:format properties per Target. If there are more than one, then it implies that content negotiation is available for the resource.
Target Resource Model:

Figure 4.1. Annotation Target
 <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <Target1> .
    
  <Target1> a <Type1> ;
    dc:format "mimetype1" .

Usage

Requirement: Find annotations which annotate a target with a given mime type.
   SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target dc:format "mimetype1" }
=> <Anno1>

See Example List

4.2 Multiple Targets

Annotations may be about multiple resources at the same time, such as Annotations that compare or contrast two resources, or make statements that are equally about several resources.

The Open Annotation model does not define any new relationships to facilitate multiple targets. The oa:hasTarget relationship is used multiple times from a single Annotation to each individual Target.

Model

Multiple Targets Model:

Figure 4.2. Multiple Targets
  <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <Target1> 
    oa:hasTarget <Target2> .

Usage

Requirement: Find annotations with multiple targets.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?t1 . ?anno oa:hasTarget ?t2 . 
    FILTER( ?t1 != ?t2 ) }
=> <Anno1>

See Example List

4.3 Inline Targets

Although the argument for embedding the Target resource's representation into an Annotation is less pervasive than embedding the Body, there are situations where doing this is useful. Examples include annotation of resources which are not available online at all, are considered likely to become unavailable in the future, or to include the exact representation of the resource that was annotated.

This is discussed in detail in the Inline Target section.

4.4 Specific Targets

Just like with the Body, it is possible for the Target to be a specific representation, or part of a specific representation, that was available from the Target at a particular point in time, or via a particular combination of HTTP headers.

This Specific Target identifies the exact combination of the resource plus any Specifiers (State, Selector and Style) and the full, unqualified resource. The identity of the Specific Target is the object of the oa:hasTarget relationship, and the full resource, the Source, is referenced from it by oa:hasSource. The Specific Target is typically identified by a URN, as an HTTP URI would imply that the exact nature of the Specific Target was available to retrieve by dereferencing the HTTP URI. The Specific Target MAY be used by multiple Annotations, but it must be understood that it is the exact combination of all of the Specifiers applied to the Source resource.

The description of exactly how to determine the representation is discussed in detail in the Specifiers section.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:SpecificResourceClassA resource which identifies part of another resource, a particular representation of a resource, a resource with with styling hints for renders, or any combination of these.
oa:hasSourceRelationshipThe relationship between a oa:SpecificResource and the resource that it is a more specific representation of.
There MUST be exactly 1 oa:hasSource relationship for each oa:SpecificResource.
Specific Target Model:

Figure 4.4 Specific Target
  <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <SpTarget1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasSource <Target1> .

Usage

Requirement: Find all of the Annotations which target a particular representation, rather than a generic resource.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource }
=> <Anno1>

See Example List

5. Specifier

Specifiers in the Open Annotation model are used to express how to determine exactly what the annotator was intending to annotate, and how. A Specifier is associated with a Specific Resource, either in the role of Body or Target. The nature of the Specifier is dependent on the sort of information it conveys, and potentially also on features of the Source resource that it is making more specific.

The Open Annotation Model defines three Specifier classes with different roles: oa:State, oa:Selector and oa:Style. They are used in that order, if present, according to the following flow diagram. A State describes how to determine the correct representation from the Source resource, then a Selector describes how to discover the correct part of that representation, and finally a Style describes how that segment should be rendered to the user. The output of this chain is the resource identified by the Specific Resource's URI.


Figure 5.0 Specifier Flow

Specifiers are intended to be able to be re-used by multiple Annotations, and are thus not linked directly to the Source resource. For example, an instance of a Selector may be re-used to select the same segment of multiple resources, or an instance of a Style may be re-used to ensure a consistent look and feel. Note, however, that the Specific Resource is not intended to be reused but may be re-used if all of the Specifiers associated with it are applicable.

The Specifier's description may be conveyed as the content of an external or embedded resource, or as RDF properties within the Annotation graph. The description SHOULD use existing standards whenever possible. If the specifier has an HTTP URI, then its description, and ONLY its description, MUST be returned when the URI is dereferenced.

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

5.1 State

The State Specifier describes the intended state of a Body or Target resource as applicable to the particular Annotation, and thus gives a consuming client the information needed to retrieve the correct representation of that resource. As web resources change over time, it might include a link to an archived copy of the Source resource, or the timestamp at which the Annotation applies to assist in discovering appropriate archived representations. Resources may have multiple representations in different formats, and the Annotation may only apply to one of them, and thus the State could describe how to retrieve the representation in the correct format directly from the Source. Other facets include fixity or checksum information to determine whether the retreived representation is the same as the annotated one, whether the resource requires authentication to retrieve, the user-agent string to send to the web server, and so forth.

The Open Annotation Core model defines two predicates which are deemed the most crucial: the timestamp for the resource and a link to an cached copy of the representation. Either of these would help a consuming client to discover an appropriate representation. It is NOT RECOMMENDED to directly annotate a cached copy, as this would make it significantly more difficult to determine whether the copy or the original is the intended target; consuming clients would assume that only the copy was intended.

Consuming clients MUST process a State Specifier before processing any supplied Selector or Style Specifier.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:StateClassA resource which describes how to retrieve an appropriate representation of the Source resource for the Annotation.
oa:hasStateRelationshipThe relationship between a oa:SpecificResource and an oa:State resource.
There MAY be 0 or more oa:hasState relationships for each SpecificResource.
oa:whenPropertyThe timestamp at which the Source resource should be interpreted for the Annotation.
There MAY be 0 or more oa:when relationships per State. Each gives an alternative timestamp at which the Source may be interpreted.
oa:cachedSourceRelationshipA link to a copy of the Source resource's representation, appropriate for the Annotation.
There MAY be 0 or more oa:cachedSource relationships per State. Each gives an alternative copy of the representation.
State Model:

Figure 5.1. State
  <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <SpTarget1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasState <State1> ;
    oa:hasSource <Target1> .
    
  <State1> a oa:State ;
    oa:cachedSource <Copy1> ;
    oa:when "timestamp1" .

Usage

Requirement: Find all of the annotations where the comment resource's representation comes from March 2012.
  SELECT ?anno WHERE { ?anno oa:hasBody ?body . ?body a oa:SpecificResource . 
    ?body oa:hasState ?state . ?state oa:when ?when .
    FILTER ( xsd:dateTime(?when) >= xsd:dateTime("2012-03-01T00:00:00Z") ) .
    FILTER ( xsd:dateTime(?when) < xsd:dateTime("2012-04-01T00:00:00Z") ) }
=> <Anno1>

See Example List

5.2 Selector

Many annotations are about part of a resource, rather than all of it. Resources can be arbitrarily large, and annotations arbitrarily precise as to their segment of interest. Examples include an area within an image or video, a range of characters in text, a time segment in an audio file or a slice of a dataset. Equally, the segment may be the Body of the Annotation, where the comment is given at a particular point in the video, or in a particular paragraph of text.

A Selector is a Specifier which describes how to determine the segment of interest from within the retrieved representation of the Source resource. The nature of the Selector will be dependent on the type of the representation for which the segment is conveyed. For example the methods used to describe a section of an Image will be very different to the methods used to discover the correct paragraph of text, or the correct slice of a dataset. The Selector may be an external or inline resource, or the information may be conveyed within the Annotation graph.

The Open Annotation Core defines one subClass of Selector, described in the following sub-section, as it applies at the web architecture level rather than being domain or media-type specific.

Selectors MUST be processed after processing any State, and before processing any Style attached to the same Specific Resource.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:SelectorClassA resource which describes the segment of interest in a representation of a Source resource
oa:hasSelectorRelationshipThe relationship between a oa:SpecificResource and an oa:Selector.
There MAY be 0 or more oa:hasSelector relationships for each oa:SpecificResource.
Selector Model:

Figure 5.2. Selector
  <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <SpTarget1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasSelector <Selector1> ;
    oa:hasSource <Target1> .
    
  <Selector1> a oa:Selector .

Usage

Requirement: Find annotations about a part of a resource.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource . 
    ?target oa:hasSelector ?select }
=> <Anno1>

See Example List

5.2.1 Fragment Selector

The web architecture defines a method of identifying a particular segment of a resource, using the fragment part of the URI. This has been used for media-type specific fragments (such as XML and PDF) and more recently for media fragments that are applicable to entire classes of resources, such as Image and Video, regardless of their exact mime type.

The Open Annotation model does NOT RECOMMMEND the use of fragment URIs for identifying segments of Targets or Bodies for the following reasons:

Thus, Open Annotation defines a Fragment Selector which is consistent with the model and allows existing and future fragment specifications to be used. The description of the segment is the syntax for the fragment identifier component of the URI, and it is included in the Annotation graph via the rdf:value property. Thus a Fragment URI may be reconstructed by concatenating the oa:hasSource resource's URI, plus a '#', plus the value of the Fragment Selector. For example in the model below, the resulting fragment URI would be: Target1#fragment1

Clients MUST process the value of the Fragment Selector based on the mime-type of the Source resource, and thus the client MUST either inspect the Source's description in the Annotation for a dc:format property or dereference the Source and look at the HTTP Content-Type header value. This is to prevent misinterpretation of the fragment identifier component, which is by definition media type dependent. For example, it is possible to construct a fragment identifiers that look like Media Fragment URIs as part of HTML anchors (for example, #xywh=1,2,3,4 also refers to this section of this HTML document, not a 3 by 4 pixel area, starting at 1,2). Clients MUST therefore also use any State information to be sure that the correct representation is being retrieved to apply the FragmentSelector to.

Furthermore, Open Annotation considers the current capabilities of fragment descriptions to be insufficient for the purposes of selecting the desired segment of a resource for an annotation:

For these reasons, the Fragment Selector is not enough, and further selectors are defined in the OAX namespace.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:FragmentSelectorClass[subClass of oa:Selector]A resource which describes the segment of interest in a representation, through the use of the fragment identifier component of a URI.
rdf:valuePropertyThe contents of the fragment identifier component of a URI that describes the segment of interest in the resource.
The oa:FragmentSelector MUST have exactly 1 rdf:value property.
Fragment Selector Model:

Figure 5.2.1. Fragment Selector
  <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <SpTarget1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasSelector <Selector1> ;
    oa:hasSource <Target1> .
    
  <Selector1> a oa:FragmentSelector ;
    rdf:value "fragment1" .

Usage

Requirement: Find annotations where the segment of interest could be described by the fragment component of a URI.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource . 
    ?target oa:hasSelector ?select . ?select a oa:FragmentSelector .
    ?select rdf:value "fragment1" }
=> <Anno1>

See Example List

5.3 Style

The interpretation of a particular Annotation may rely on rendering style being consistent between clients. For example, if the Body refers to the part of an image highlighted in yellow, as compared to the red highlighted part, then the highlight color needs to be maintained. Equally, annotators may convey information via the styling alone, perhaps only to themselves but between interoperable systems, so in order for this implicit information not to be lost, the styling needs to be consistent. For example, an annotator may know that green highlights are intended to be referred back to, but that they disagree with red highlighted sections.

To this end, Open Annotation introduces the Style Specifier class. A Style is a resource which expresses the rendering qualities for a particular Specific Resource, likely in a media-type dependent way. Cascading Stylesheets or XSLT Stylesheets are two technology specific formats that might be applicable, for example.

Styles may also be used to convey processing instructions for resources intended for machine consumption, and are not intended to be displayed to a human user. For example, a Style might convey that the resource should be used to update a database record.

Styles SHOULD be processed only after processing any States and Selectors associated with the Specific Resource. If a client cannot understand or act upon the style, then it may continue to render the selection or resource regardless, at its discretion. The Open Annotation Core model does not currently define any cross-domain, media-type independent Styles; please see the Open Annotation Extension namespace for defined subclasses.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:StyleClassA resource which describes the style in which the selection or resource should be rendered.
oa:hasStyleRelationshipThe relationship between a oa:SpecificResource and the oa:Style.
There MAY be 0 or more hasStyle relationships for each SpecificResource.
Style Model:

Figure 5.3. Style
  <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <SpTarget1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasStyle <Style1> ;
    oa:hasSource <Target1> .
    
  <Style1> a oa:Style .

Usage

Requirement: Find all of the annotations for which style information is provided about a target.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource .
    ?target oa:hasStyle ?style . }
=> <Anno1>

See Example List

5.4 Alternative Specifiers

The processing order for Specifiers is: State then Selector then Style. This ensures that the correctly styled, correct part of the correct representation of the resource is rendered by the client to the user.

If there are multiple Specifiers of the same type, then they are considered to be alternatives, and the consuming client MUST select only one of them to use. The method for determining the choice is not specified and will be dependent on many factors, including the capabilities of the client and the expressiveness of the individual Specifiers.

If multiple Specifiers are needed to work in conjunction, then a combination Specifier should be defined that references the individual Specifier classes. If the order and nature in which these are processed is important, it is left up to communities who may have this requirement to produce such a class.

Model

Alternative Selectors Model:

Figure 5.4. Specifier Combination
  <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <SpTarget1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasSelector <Selector1> ;
    oa:hasSelector <Selector2> ;
    oa:hasSource <Target1> .

Usage

Requirement: Find all of the Selectors for a particular Specific Resource.
  SELECT ?sel WHERE { <SpTarget1> oa:hasSelector ?sel}
=> <Select1>, <Select2>

See Example List

5.5 Inline Specifiers

As with other resources, it may be useful to embed Specifiers of any type within the Annotation graph. Please see the Inline Specifier section for further details.

6. Inline Resources

The web architecture assumes that every resource has a URI, and furthermore the expectation is that they are available for retrieval from HTTP URIs. Some clients, however, may not be able to generate dereferencable URIs on their own for all of the resources that are created as part of the annotation process. This includes the Body, any Specifiers or other user generated information, but also potentially the Target if it is not available online.

The Open Annotation model uses the "Representing Content in RDF" specification to include the representation of such resources directly within the Annotation graph. The resource is assigned a non-resolvable URN, and an appropriate class from the Content in RDF ontology, such as cnt:ContentAsText or cnt:ContentAsBase64. While the sub-sections below make an arbitrary, although common, choice between these options, it is important to note that this is not intended to be the only choice for the situation. For consistency and simplicity, even if the resource is in RDF, it SHOULD be included as a serialization using the Content in RDF specification as above. Consuming clients must necessarily be able to parse RDF to consume the Annotation, and thus can also parse the serialized resource.

It is important to have a model that deals gracefully and consistently with both online, dereferencable resources, and embedded resources identified by a URN. In both cases, the content is expressed as a resource, rather than using only a string literal for embedded content. Both cases deal with any content type, including binary data, and deal with any type of resource within the Open Annotation model: Body, Target or Specifier.

6.1 Inline Body

Previous annotation systems that only permitted textual Bodies might have used a property with a string literal, however the Open Annotation model employs the Content in RDF specification for consistency with non-textual Bodies and other types of resource. The use of cnt:ContentAsBase64 is RECOMMENDED for Bodies with binary content.

It is important to note that other classes, such as the type of media for the resource (Text, Image, Video, Audio, etc.), SHOULD also be assigned alongside the ContentAsText class. This is not depicted in the model below.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
cnt:ContentAsTextClassA class assigned to the Body for embedding textual resources within the Annotation graph.
cnt:charsPropertyThe character sequence of the content.
There MUST be exactly 1 cnt:chars property associated with the ContentAsText resource.
dc:formatPropertyThe mimetype of the content.
There SHOULD be exactly 1 dc:format property associated with the resource, but MAY be 0.
Inline Body Model:

Figure 6.1. Inline Body
  <Anno1> a oa:Annotation ;
    oa:hasBody <InBody1> ;
    oa:hasTarget <Target1> .
    
  <InBody1> a cnt:ContentAsText ;
    cnt:chars "content1" ;
    dc:format "mimetype1" .

Usage

Requirement: Find all of the annotations with embedded, textual comments.
  SELECT ?anno WHERE { ?anno oa:hasBody ?body . ?body a cnt:ContentAsText }
=> <Anno1>

See Example List

6.2 Inline Target

In order to annotate and, at the same time, share a resource that is not available on the web, it may be convenient for clients to embed arbitrary content within Annotation graphs. This would also allow the specific representation of a dynamic target to be embedded. For non-binary content, the ContentAsText class should be used instead.

It is important to note that other classes, such as the type of media for the resource (Text, Image, Video, Audio, etc.), SHOULD also be assigned alongside the ContentAsBase64 class. This is not depicted in the model below.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
cnt:ContentAsBase64ClassA class assigned to the Target for embedding binary resources within the Annotation graph.
cnt:bytesPropertyThe character string representing the Base64 encoded byte sequence of the content.
There MUST be exactly 1 cnt:bytes property associated with the ContentAsBase64 resource.
dc:formatPropertyThe mimetype of the content.
There SHOULD be exactly 1 dc:format property associated with the resource, but MAY be 0.
Inline Target Model:

Figure 6.2. Inline Target
  <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <InTarget1> .
    
  <InTarget1> a cnt:ContentAsBase64 ;
    cnt:bytes "enc-content1" ;
    dc:format "mimetype1" .

Usage

Requirement: Find all of the annotations with embedded, binary targets.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a cnt:ContentAsBase64 }
=> <Anno1>

See Example List

6.3 Inline Specifier

Specifiers may be embedded within the Annotation graph using exactly the same method as for Bodies or Targets.

Model

Inline Specifier Model:

Figure 6.3. Inline Specifier
  <Anno1> a oa:Annotation ;
    oa:hasBody <Body1> ;
    oa:hasTarget <SpTarget1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasSelector <Selector1> ;
    oa:hasSource <Target1> .
    
  <Selector1> a cnt:ContentAsText ;
              a oa:Selector ;
    cnt:chars "content1".

Usage

Requirement: Find all of the annotations with embedded selectors for a target.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource .
    ?target oa:hasSelector ?sel . ?sel a cnt:ContentAsText }
=> <Anno1>

See Example List

6.4 Publishing Inline Resources

As with the serialization of Annotations, embedded resources should be treated in the same way when encountered and republished with their own HTTP URIs. If a system publishes an embedded resource at a new HTTP URI, then it SHOULD express the oa:equivalent relationship between the resource's URN and the new URI from which it is available. As the graph has changed it SHOULD then update the oa:generated timestamp on the Annotation. The system MAY also remove the embedded resource from the graph and reference only the dereferencable URI, at its discretion.

The model below uses an embedded Body resource as an example only, exactly the same scenario applies for embedded Targets and Specifiers.

Model

The Open Annotation model uses:
Vocabulary ItemTypeDescription
oa:equivalentRelationshipThe subject and object resources of the oa:equivalent relationship represent the same resource, but may have different metadata such as when they were published.
The Annotation graph MAY include 0 or more instances of the oa:equivalent relationship between embedded resources and their published counterparts.
Inline Processing Model:

Figure 6.4. Publishing Inline Resources
 <Anno1> a oa:Annotation ;
    oa:hasBody <InBody1> ;
    oa:hasTarget <Target1> .
    
  <Body1> a cnt:ContentAsText ;
    oa:equivalent <Body2> ;
    dc:format "mimetype1" ;
    cnt:chars "content1" .

Usage

Requirement: Find all of the other identities assigned to a resource.
   SELECT ?body WHERE { { ?body oa:equivalent <InBody1> } 
    UNION { <InBody1> oa:equivalent ?body } }
=> <Body2>

See Example List

7. Model Summary

Summary of the Open Annotation Core Model:

Figure 7.0. Model Summary
  <Anno1> a oa:Annotation ;
	  a <Class1> ;
    oa:hasBody <InBody1> ;
    oa:hasTarget <SpTarget1> ;
    oa:hasTarget <Target2> ;
    oa:annotator <Agent1> ;
    oa:annotated "datetime1" ;
    oa:generator <Agent2> ;
    oa:generated "datetime2" ;
    oa:modelVersion <Version1> .
    
  <InBody1> a cnt:ContentAsText ;
            a <Type1> ;
    oa:equivalent <Body2> ;
    dc:format "mimetype1" ;
    cnt:chars "content1" .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasState <State1> ;
    oa:hasSelector <Selector1> ;
    oa:hasStyle <Style1> ;
    oa:hasSource <Target1> .
    
  <State1> oa:cachedSource <Copy1> .

A. References

[Creative Commons]
Creative Commons, Creative Commons, May 18 2008
[Content in RDF]
Representing Content in RDF 1.0, Koch, J. Velasco, C. 29 October 2009
[DC Elements]
Dublin Core Metadata Elements, DCMI Recommendation, 18 December 2006.
[DC Terms]
DCMI Metadata Terms, DCMI Usage Board, 18 December 2006.
[FOAF]
FOAF Vocabulary Specification 0.91, D. Brickley, L. Miller. 2 November 2007.
[JCDL 2010]
Making Web Annotations Persistent over Time, Sanderson, R, Van de Sompel, H. Procs. of the Joint Conference on Digital Libraries 2010, Surfers Paradise, Australia. (Presentation available)
[Memento]
Memento: Time Travel for the Web, Van de Sompel, H, Nelson, M, Sanderson R. October 2010.
[RDF]
RDF Primer, F. Manola, E. Miller, Editors. W3C Recommendation, 10 February 2004.
[RDF Vocabulary]
RDF Vocabulary Description Language 1.0: RDF Schema, Dan Brickley and R.V. Guha, Editors. W3C Recommendation, 10 February 2004.
[RFC 3986]
Uniform Resource Identifier (URI): Generic Syntax, Berners-Lee, T., Fielding, R., and L. Masinter, STD 66, RFC 3986, January 2005.

B. Acknowledgements

This specification builds upon the work from many previous annotation efforts, including in particular:

The editors would like to acknowledge the financial support of the Mellon Foundation for the Open Annotation Collaboration and funding the initial reconcilliation between the Annotation Ontology and Open Annotation Collaboration models.

The editors would like to thank the following for their valuable contributions:

C. Change Log

Date Editor Description
2012-05-09 rsanderson License Correction
2012-05-01 rsanderson W3C Community Draft
2012-04-05 rsanderson Internal Draft 2
2012-03-30 rsanderson Internal Draft 1