1. Introduction

Annotating, the act of associating one piece of information with one (or more) other piece(s) of information, is a pervasive activity shared by all humanity across all walks of life. 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 resources mentioned on Twitter could all be considered as annotations associated with the original resource. There are a plethora of closed and proprietary web-based "sticky note" systems, such as Google's Sidewiki, and stand-alone multimedia annotation systems. The primary complaint about these systems is that the annotation is locked in to the web site or tool which was used to create them, and cannot be seen, managed or leveraged in any way outside of it.

Annotating is also a pervasive element of scholarly practice for both the humanist and the scientist. It is a method by which scholars organize existing knowledge and facilitate the creation and sharing of new knowledge. It is used by individual scholars when reading as an aid to memory, to add commentary, and to classify, but more importantly it can also facilitate shared editing, scholarly collaboration, and pedagogy. Annotations can have value in their own right, as a means of scholarly communication.

Yet scholars also remain dissatisfied with the options available for annotating digital resources. Scholars that wish to annotate online resources are in the same position of having to learn different annotation clients for different content repositories, have no easy way to integrate annotations made on different systems or created by colleagues using other tools, and are often limited to simplistic and constrained models of annotation.

The Open Annotation data model provides an interoperable method of expressing annotations such that they can easily be shared between platforms, with sufficient richness of expression to satisfy scholars' needs while remaining simple enough to also allow for common use cases such as attaching a piece of text to a single web resource. Annotations are modeled as a set of connected resources, including a body and one or more targets, where the body is somehow about those targets.

Unlike previous attempts, the Open Annotation system does not prescribe a protocol for creating, managing and retrieving annotations. Instead it describes a web-centric method, founded on the ideas of the Linked Data initiative, which enables discovery and sharing of annotations without clients or servers having to agree on a particular set of operations on those annotations. This publish/discover approach is described in a companion document (not yet available).

1.1 Namespaces Used

This specification uses the following namespaces and prefixes to indicate those namespaces:

Prefix	Namespace URI	Description
cnt	http://www.w3.org/2008/content#	Content in RDF [Content in RDF]
dc	http://purl.org/dc/elements/1.1/	Dublin Core elements [DC Elements]
dcterms	http://purl.org/dc/terms/	Dublin Core terms [DC Terms]
dcmitypes	http://purl.org/dc/dcmitype/	Dublin Core types [DC Types
foaf	http://xmlns.com/foaf/0.1/	Friend of a Friend vocabulary [FOAF]
oac	http://www.openannotation.org/ns/	Open Annotation vocabulary [OAC]
rdf	http://www.w3.org/1999/02/22-rdf-syntax-ns#	RDF vocabulary [RDF Vocabulary]
rdfs	http://www.w3.org/2001/01/rdf-schema#	RDF Schema vocabulary [RDF Vocabulary]

1.2 Notes about Examples

Examples of the data model are available in separate, themed documents. Links to the relevant sections are included below, and will be updated as more examples become available.

Current example documents:

• Hubble Example
• Scholarly Edition Example

2. Open Annotation Guiding Principles

1. The Open Annotation effort focuses on interoperability for annotations across clients, services and collections. It does not in any way prescribe client user interface, nor internal client architecture.
2. The focus is on sharing annotations for scholarly purposes. However, in order to maximize the likelihood of adoption, care will be taken to make the interoperability framework readily applicable in other domains.
3. In alignment with the prevailing view, an Annotation is a document containing references to the Body and Target, which the Body is somehow about.
4. Contrary to the prevailing view, in which the Body is textual, Annotations must allow for both Body and Target of any media type.
5. Contrary to the prevailing view, in which the author of the Annotation and the author of the Body are the same, the Annotation, Body, and Target can have different authorship.
6. The previous principles lead to an annotation model in which all core entities are Web resources: Annotation, Body, and Target should all be identified with HTTP URIs where possible.
7. Many Annotations involve parts of resources (image regions, slides of a video), and therefore support must be provided for resource segment addressing. Preferably this should be done with URIs (eg. URI fragments), but extensibility must be provided for cases where the use of URIs for segment addressing is not possible.
8. A variety of more complex scholarly annotation scenarios involve multiple Targets; the model must support this.
9. URI-addressable resources are ephemeral: the representations obtained by dereferencing their URI may change over time. Certain Annotations pertain to specific representations of Body and/or Target, and therefore they risk to be misinterpreted once those representations changed. Measures should be provided that can help in avoiding misinterpretations of Annotations, including the expression of timestamps and fixity information for Body and Target.
10. The annotation model should provide a set of top-level classes/entities and properties/relationships that will maximize interoperability across annotation clients, servers, collections and applications – but which can be extended and refined for specialist use cases.
11. In order to increase the likelihood of adoption, and in alignment with the goal of sharing annotations, no client-server protocol for publishing/updating/deleting annotations will be specified. Rather, the specifications will take a perspective whereby clients publish annotations to the Web and make them discoverable using common Web approaches. Such an approach does not require a preferred annotation server for a client, yet it does not preclude one either.

3. Open Annotation Data Model

3.1 Baseline Model

An Annotation is a document identified by an HTTP URI that describes an association created between a Body resource and a Target resource. The Body must be somehow "about" the Target for it to be considered the body of an Annotation. This gives rise to a tripartite base model with the same basic structure as that of Annotea [Annotea]

Figure 1: Baseline Model

Both the Body and the Target of the Annotation can be any resource on the web, identified by a URI. As such, they can have representations in any format or language (or no language), or have no representations at all, such as for abstract resources that denote a concept.

Ontology

The Open Annotation ontology defines the following classes:

oac:Annotation (A-1)

A document identified by an HTTP URI that describes, at least, the Body and Target resources involved in the annotation.

oac:Body (B-1)

The body of the annotation. The Body is somehow about the Target resource. It is the information which is annotating the Target.

oac:Target (T-1)

The resource that is being annotated.

And the following relationships:

oac:hasBody

The relationship between Annotation and Body.

oac:hasTarget

The relationship between Annotation and Target.

Please note that both oac:Body and oac:Target should not be interpreted as exclusive classes when considered across multiple Annotations, as the Body of one Annotation may be the Target of another.

Examples

• Hubble Example

3.2 Serialization

Dereferencing the HTTP URI of the Annotation document results in an RDF serialization of an instance of this data model. Any of the RDF serialization formats are permissible, however RDF/XML is recommended. It may be desirable to allow clients to request different serializations through the use of Content Negotiation.

Figure 2: Serialization of an Annotation

Example of an alternate serialization (RDFa)

• Gatsby Example

3.3 Additional Properties and Relationships

As an Annotation is a resource with a URI, additional properties and relationships can be associated with it. It should have a timestamp of when the annotation relationship was created (dcterms:created) and a reference to the agent that created it (dcterms:creator). It is recommended that the object of dcterms:creator relationship be a foaf:Agent, and it have at least foaf:name and foaf:mbox properties.

Resources referenced by additional relationships may themselves have additional properties and relationships. The set of relationships below is by no means exhaustive: other relationships and properties may also be used.

It is also important to note that the properties and relationships of the Annotation do not necessarily apply to either the Body or the Target. The same property may be used on each of the three different resources with different values.

It is also possible to have additional relationships between resources present in the model. There may be a predicate that expresses the relationship between the Body and the Target, for example. The oac:annotates relationship is used to demonstrate this in Figure 3.1. Example documents may contain additional uses of these constructions.

Figure 3.1: Additional Properties and Relationships

Ontology:

Classes:

foaf:Agent (U-1)

An agent, in this case the creator of the Annotation

Relationships:

dc:title

The name of the Annotation

dcterms:creator

The creator of the Annotation

dcterms:created

The time and date at which the Annotation was created

foaf:name

The name of the creator

foaf:mbox

The email address of the creator

oac:annotates

The subject resource is the body of an annotation and is somehow about the object resource

Examples

• Hubble Example
• Gatsby Example
• Scholarly Edition Example

3.4 Annotation Types

While oac:Annotation is the base class for Annotations, there can be many other more specialized types. Many systems allow users to reply to Annotation, for example, and one might want to type a particular annotation as an oac:Reply in order to distinguish it from other sorts of Annotation.

Additional classes can also be used for additional requirements of the Annotation document. For example, a hypothetical oac:PhotoCommentary might require that the target be an image (a dcmitypes:Image). In this case the model would be exactly the same as Figure 2 above, but with oac:PhotoCommentary in place of oac:Annotation.

Figure 4: Additional Types of Annotation: oac:Reply

Ontology

Classes:

oac:Reply

A subClass of oac:Annotation which indicates that it is a reply to another Annotation.

A list of known subClasses of oac:Annotation is available. The list is maintained separately from this guide for ease of discoverability and maintenance.

Examples

• Hubble Example
• Hubble Example

3.5 Inline Information

The baseline model assumes that all resources have URIs, and are available on the web. Some clients may not be able to generate URIs on their own for the resources that are created as part of the annotation process. For example, it may be necessary for the client to transmit a single document which includes the Body as plain text, and any other user generated information.

To allow the client to embed the Body directly into the Annotation document, we assign a unique non-resolvable URI (called a URN) as the identifier for the Body. It is suggested that an identifier in the urn:UUID scheme be used, however any URN is possible. This would be appropriate for clients that function primarily offline, or cannot generate URIs for the text entered by the user. Servers which discover these URIs should rewrite them into HTTP URIs which they control and assert an equivalence between the HTTP URI and the original URN. More information about this process is available in the companion publish/discovery document (not yet available).

The Open Annotation data model leverages the W3C's "Representing Content in RDF" [Content in RDF] specification to include information directly within the Annotation document.

Figure 5.1: Inline Body

Ontology

Classes defined elsewhere:

cnt:ContentAsText

Relationships defined elsewhere:

cnt:chars

The representation of the resource, as plain text. In this case the resource is the Body of the Annotation.

cnt:characterEncoding

The name of the character encoding of the object of the cnt:bytes property, such as "utf-8" or "ascii"

Examples

• Hubble Example
• Gatsby Example

3.6 Multiple Targets

Annotations can be about multiple resources, such as Annotations that compare or contrast two resources. The data model therefore needs to allow for multiple Targets for a single Annotation. This can be accomplished by expressing multiple hasTarget relationships.

While the Annotation normally stands for the relationship between the Body and the Target node, if there are different relationships between the Body and individual Targets in the multiple Target scenario, it is encouraged to be explicit and include these relationships in the RDF graph.

Figure 6: Multiple Targets

Examples

• Hubble Example
• Gatsby Example
• Scholarly Edition Example

3.7 Segments of a Resource and Constrained Resources

The user (or software agent) must be able to select a part of the resource as the Body or Target for an Annotation, not just the entire resource. Many Annotations have this requirement, as resources can be arbitrarily large and frequently there is only a small section which is of interest. For example, the Target may be an area within an image or video, or the Body may be a paragraph within a longer text.

There are several ways in which this can be accomplished. The first two approaches use the three node model described above, and latter approaches introduce a new subClass of oac:Target for situations in which the base model is insufficient.

3.7.1 Fragment URIs

A fragment URI normally identifies a part of a resource, and the method for constructing and interpreting these URIs is dependent on the media type of the resource. In general, fragment URIs are created by appending a fragment that describes the section of interest to the URI of the full resource, separated by a '#' character. For more information about fragments in URIs, please see RFC 3986 [RFC 3986].

It is recommended that when a definition exists for how to construct a fragment URI for a particular document format, and such a fragment would accurately describe the section of interest for the Annotation, then this technique should be used.

The known media types that define fragment construction rules are:

X/HTML [RFC 2854 RFC 3236]

HTML and XHTML use fragments to refer to a specifically named element within the document. If the element is an "A" tag, then it refers to the name attribute. Otherwise it refers to the id attribute in XHTML.

Examples

• http://www.example.net/foo.html#namedSection
  The section named as "namedSection".
• http://www.example.net/foo.xhtml#identifiedElement
  The Element with the id attribute "identifiedElement"

PDF [RFC 3778]

Fragment identifiers for PDF use one of several methods, however the most revelant are:

• page=(page)
  The specified page
• viewrect=(left),(top),(wd),(ht)
  A rectangle with x and y of left and top, and width and height of wd and ht, in pixels

These can be combined with an '&' character to identify a rectangular area on a particular page.

Examples

• http://www.example.net/foo.pdf#page=10
  All of page 10 of the PDF.
• http://www.example.net/foo.pdf#page=10&viewrect=20,100,50,60
  A rectangle starting at 20 pixels in from the left, and 100 down from the top, with a width of 50 and a height of 60.

Plain Text [RFC 5147]

Plain text fragment identifiers use either character positions or line positions. The first character is character 1, and similarly the first line is line 1, so the position before the first character/line is position 0. The range extends until the end point, which is the point after the given character or line.

Examples

• http://www.example.org/foo.txt#char=0,10
  The first through 10th characters of foo.txt
• http://www.example.org/foo.txt#line=1,5
  The second through fifth lines of foo.txt

XML [RFC 3023]

The W3C define a specification called XPointer, essentially a superset of XPath, which can be used to refer to elements and sets of elements in an XML document. For more information please see http://www.w3.org/TR/WD-xptr

Examples

• http://www.example.net/foo.xml#xpointer(/a/b/c)
  The element c, whose parent is b, whose parent is the root node a.
• http://www.example.net/foo.xml#xpointer(id("chap1"))
  The element in the XML document that has the id attribute value of 'chap1'

As the fragment URI identifies the resource that is the Body or Target of the Annotation, the data model is the same as the baseline described in section 2.1 with one exception. It is strongly recommended that the dcterms:isPartOf relationship be used to link back to the resource's URI without the fragment, for user agents that do not understand fragments and for ease of querying.

Figure 7.1: Fragment URIs

Ontology

Relationships Defined Elsewhere:

dcterms:isPartOf

The related resource is logically part of the subject

Examples

• Hubble Example
• Gatsby Example
• Scholarly Edition Example

3.7.2 Media Fragment URIs

The W3C Media Fragment URI specification [Media Fragments] allows the creation of a URI that identifies a segment of image, video and audio resources for common scenarios. In contrast to (X)HTML fragments, where the fragment's target must be embedded in the data by the creator, Media Fragments can be generated by others as needed by following conventions.

The Media Fragment specification defines four fragment parameters, used in the same way as for PDFs and plain text, described above. Multiple parameters can be given, separated by an ampersand ('&').

Spatial (#xywh=)

The spatial parameter can be used to define a rectangular segment of an image or video. It gives the x and y coordinates, and then then width and height of the rectangle. Non-rectangular segments cannot be identified using the Media Fragment specification.

Example

• http://www.example.net/foo.png#xywh=160,120,320,240
  A 320 by 240 box, starting at x=160 and y=120

Temporal (#t=)

There are three styles of temporal parameter: Normal Play Time (npt), SMPTE (smpte) and Wall Clock (clock). The type of parameter is given at the beginning, followed by a colon (':') and then a value for the range of time. Normal Play Time is the easiest, and consists of the starting time in seconds and the end point in seconds separated by a comma (',').

Example

• http://www.example.net/foo.mpg#t=npt:10,20
  Starting just before the 10th second, and ending just before the 20th.

Named (#id=) and Tracks (#track=)

Similar to the X/HTML style of fragment, this allows the creation of segments based on identifier or by the name of a particular track.

Example

• http://www.example.net/foo.ext#id=1
  The section with the identifier '1'
• http://www.example.net/foo2.ext#track=subtitle
  The track named 'subtitle'

The model and ontology for Media Fragment URIs is identical to that of fragment URI schemes defined explicitly per media type, as above in Figure 7.1.

Examples

• Hubble Example

3.7.3 Constrained Targets

In order to allow for resource segments which cannot be described using fragment URIs, the recommended approach is to define a new resource identified by a URN (again, a urn:UUID is appropriate) as the Target of the Annotation, which we call a ConstrainedTarget (CT-1). We then describe how that resource is constrained in a Constraint resource (C-1), and link from the ConstrainedTarget to the full resource (T-1) using the oac:constrains predicate. The Constrained Target should have only one Constraint; see the section on Multiple Constraints below if more are required.

The nature of the Constraint description will be dependent on the type of the resource for which the segment is being conveyed. It is then up to the annotation client to interpret the segment description with respect to the full resource. For example, an SVG path element could be used to describe an area within an image, a SPARQL or SQL query could be used to describe a slice of a database.

This Constraint resource cannot be attached directly to the Body or Target, as it is only true within the context of the Annotation rather than true in all circumstances. This is a restriction of the RDF data model, as all statements must be globally true, not only true within a particular graph or description.

This approach can be used to constrain resources in ways other than to describe a part of the resource. For example, one might want to annotate an image resource only as it appears within a particular HTML page to say that it looks out of place. A second example is to annotate a particular version of a resource, and for this use case please see section 3.8 below.

Figure 7.3: Constraints

Ontology

Classes:

oac:ConstrainedTarget (P-1)

The ConstrainedTarget is the target of the annotation. It is constrained from another resource (the full resource, of which the target is a part) and constrained by a third resource, the Constraint.

oac:Constraint (SD-1)

The Constraint is a resource which describes how to constrain another resource in a particular way.

Relationships:

oac:constrains

The relationship from the ConstrainedTarget to the full resource being constrained.

oac:constrainedBy

The relationship from the ConstrainedTarget to the Constraint resource that describes how the full resource is constrained

Examples

• Hubble Example
• Scholarly Edition Example

3.7.3.1 Inline Constraints

It is possible to include the Constraint information inline within the Annotation document using the same technique as used for including the Body, described in section 3.5. The Constraint is given a URN (normally a urn:UUID) and then the Constraint information is included as the value of the cnt:chars property. The requirements for doing this are the same as for including the Body inline within the Annotation document.

Figure 7.3.1: Inline Constraints

Examples

• Hubble Example

3.7.3.2 RDF Constraints

Instead of including the Constraint description in a single string value, it may be more appropriate to embed the information within the Annotation document directly using new relationships specific to the type of Constraint. For example, rather than requiring the client to parse out the required information from a string, it may be easier to retrieve the information directly from the RDF graph.

Examples of appropriate uses would include segment descriptions that do not have an external standard that could be applied, and trivially simple segment descriptions where it would be significantly more work to parse the inline data than just to inspect the RDF graph. For example, an SVG path does not make sense to be included in the RDF graph directly, however it would be appropriate if the Constraint is a description of a range of text by using a copy of text itself, along with the text immediately before and after.

Figure 7.3.2: RDF Constraints

Examples

• Hubble Example

3.7.4 Constrained Body

The Body can be constrained in exactly the same way as the Target of the Annotation.

Example requirements for this might be when one section of a longer text is an annotation on another resource, or when part of a video discusses a particular resource but it would not be appropriate to model the entire video as the Body of the Annotation.

Figure 7.4: Constrained Body

Examples

• Hubble Example

3.7.5 Multiple Constraint Precedence

It is possible that multiple constraints need to be used in order to ensure that the annotation's body or target are fully and correctly described. There are several use cases for when this is important, that fall under two broad areas:

1. Express the equivalence between two constraints.
   For example, this would enable cross-community interoperability when there are multiple Constraint classes that express the same information. In this case, an implementation might use any of the Constraints and arrive at the correct interpretation of the Annotation's body or target.
2. Express a further constraints on an already constrained resource.
   For example, an image might change over time and the annotation involves a non-rectangular segment of a particular version of that image (see section 3.8 below on Time Dependent Annotations). In this case, implementations must process all of the Constraints in order to arrive at the correct interpretation of the Annotation's body or target.

This specification recognises the requirement for explicit constraint precedence within the model, but does not provide a final solution. Instead we invite further feedback on the suggested implementation described in this discussion document. The Open Annotation Collaboration appreciates your patience and engagement with this complicated issue.

3.7.6 Constraint Type List

The different types of Constraint that are known to the Open Annotation community are maintained in a separate document for ease of discovery.

3.8 Time Dependent Annotations

The data served from a URI at any given time (the representation) is not necessarily the same as the representation served at any other time. For some resources the data is very frequently different, as in the case of news pages, search results and so forth. An Annotation is likely to apply only to the resource as it was at the time of the creation of the Annotation. Furthermore, the Annotation could be created at a different time than the resources involved.

The data model distinguishes three different types of annotation, with respect to time. These can be distinguished via the use of the oac:when property from either the Annotation or the Body and Targets.

1. Timeless Annotations: These Annotations are always relevant, and thus time is not a concern. The Annotation might be about the semantics of the resource, rather than the data served from it. For example, the Content "This is the homepage of CNN" would be true of the Target http://www.cnn.com/ regardless of what was currently on the page.
   Timeless Annotations do not need a timestamp for when to interpret the resources involved in the Annotation, and hence the model is the same as the baseline model depicted in Figure 1.
2. Uniform Time Annotations: These Annotations are valid at a particular time, and all of the resources involved (the Content and the Targets) should be interpreted at that time. This would occur when the Content was created at the time the Target resource was delivering the data that the Content was about. For example, a tweet about the current stories on the CNN home page.

   Uniform Time Annotations need a single timestamp. This is attached to the Annotation node using the oac:when property.

   Figure 8.1: Uniform Time Annotations

3. Varied Time Annotations: These Annotations are also dependent on time, however the resources involved should be interpreted at different times. This would occur when the Body was created at a different time to the time of the state of the Target resource that it is about. An example content might be a blog post about the CNN home page of the previous day.

   Varied Time Annotations need a timestamp for each resource involved. They are attached to an oac:WebTimeConstraint for the resource, which records the timestamp using the oac:when property.

   Figure 8.2: Varied Time Annotations

It is possible to retrieve appopriate representations for a resource involved in an Annotation using the Memento extension to HTTP [Memento]. For further information about persistent annotations, please see our JCDL 2010 paper [JCDL 2010].

Ontology

oac:WebTimeConstraint

A Constraint that records a timestamp of when the resource applies to the Annotation

oac:when

The timestamp at which the resource(s) should be interpreted. If attached to an Annotation, it refers to the Content and Targets. If attached to a ConstrainedResource, it refers to the resource which that resource constrains.

Examples

• CNN Example

3.9 Structured Data Annotations

A common set of use cases for annotation is annotating data with other data, rather than with information intended for human consumption. It may be desirable, for example, to annotate text with the identifiers of the resources named or described, such as associating identifiers for places with mentions of the locations. Equally, the data may be more complex, involving relationships between resources, further properties and so forth.

The approach taken by the Open Annotation Data Model is to have an Annotation where the body is intended for machines, rather than humans. A review of a product could be considered an annotation where the rating and commentary are in the body, and the product is the target.

All of the previous requirements and principles apply: the Body is a document which contains the machine readable information, which is somehow "about" the target or targets. Further relationships and properties can be attached to the body, such as creator and format, and between the body and other resources. Please note that the other patterns, such as the use of Constraints, can also be applied to the Body of a DataAnnotation.

The Body resource may participate in other Annotations with different roles, it could be the Target of a further annotation or the Body in an Annotation intended for humans if the resource is also easily interpretable such as XHTML with embedded RDF or microformats. Thus the intention of the creator of the Annotation that it be interpreted by machines is signalled by the use of the oac:DataAnnotation subclass.

If the information is encoded in RDF, please note that the assertions are being made by the creator of the Body resource, not the creator of the Annotation resource. This is important for the web of trust and similar concepts. Secondly, the identifier(s) for the target(s) of the annotation can be used within the RDF to further clarify the relationships or properties being asserted.

Figure 9: Structured Data Annotations

Ontology

The following class is defined to support machine readable annotations:

oac:DataAnnotation

An annotation in which the Body is intended for consumption by machines.

Examples

• Scholarly Edition Example

3.9.1 Inline Data Annotations

As with inline Annotation Bodies intended for humans, it is possible to embed the data within the Annotation document. The Content in RDF specification again, along with the dc:format property to inform the processing application of the type of data that it should expect from the inlined content. This content can be any sort of data, and might require the use of other subClasses from the Content in RDF specification such as ContentAsBase64 or ContentAsXML.

Note that it would be possible to include RDF using various techniques, including Named Graphs and reification. For consistency, we recommend the use of ContentAsText unless there is a requirement or use case that other techniques can solve more easily.

Figure 9.1: Inline Data Annotations