This version:
Latest version:
Previous version:
Robert Sanderson, Los Alamos National Laboratory
Herbert Van de Sompel, Los Alamos National Laboratory


The Open Annotation Data Model specifies an approach for associating annotations with resources, using a methodology conformant with the Architecture of the World Wide Web and the Linked Data initiative. It draws on the Annotea model, as well as more recent extensions of that model.

Table of Contents

1. Introduction
     1.1 Namespaces Used
     1.2 Note about Examples

2. OAC Guiding Principles

3. OAC Data Model
     3.1 Baseline Model
     3.2 Serialization of Model
     3.3 Additional Properties and Relationships
     3.4 Annotation Types
     3.5 Inline Information
     3.6 Multiple Targets
     3.7 Segments of a Resource and Constrained Resources
         3.7.1 Fragment Identifiers
         3.7.2 Media Fragment Identifiers
         3.7.3 Constrained Targets
    Inline Constraint Data
    RDF Constraint Data
         3.7.4 Constrained Body
     3.8 Time Dependent Annotations

4. References


A. Acknowledgements
B. Change Log

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 Content in RDF [Content in RDF]
dc Dublin Core elements [DC Elements]
dcterms Dublin Core terms [DC Terms]
dcmitypes Dublin Core types [DC Types
foaf Friend of a Friend vocabulary [FOAF]
oac OAC vocabulary [OAC]
rdf RDF vocabulary [RDF Vocabulary]
rdfs 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:

2. OAC Guiding Principles

  1. The OAC 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. OAC 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.


The OAC 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:

The relationship between Annotation and Body.
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.


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)

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


foaf:Agent (U-1)
An agent, in this case the creator of the Annotation
The name of the Annotation
The creator of the Annotation
The time and date at which the Annotation was created
The name of the creator
The email address of the creator
The subject resource is the body of an annotation and is somehow about the object resource


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


A subClass of oac:Annotation which indicates that it is a reply to another Annotation.
A hypothetical subClass of Annotation in which the single Target must be an image.
A resource which is an image


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 OAC 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


Classes defined elsewhere:
Relationships defined elsewhere:
The representation of the resource, as plain text. In this case the resource is the Body of the Annotation.
The name of the character encoding of the object of the cnt:bytes property, such as "utf-8" or "ascii"


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


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.


    The section named as "namedSection".
    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.


    All of page 10 of the PDF.
    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.


    The first through 10th characters of foo.txt
    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


    The element c, whose parent is b, whose parent is the root node a.
    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


Relationships Defined Elsewhere:
The related resource is logically part of the subject


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.


    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 (',').


    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.


    The section with the identifier '1'
    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.


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


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.
The relationship from the ConstrainedTarget to the full resource being constrained.
The relationship from the ConstrainedTarget to the Constraint resource that describes how the full resource is constrained

Examples 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 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


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


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 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:TimeConstraint 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].


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.


3. References

Kahan, J. Koivunen, M. et al. "Annotea: An Open RDF Infrastructure for Shared Web Annotations" Computer Networks 39 (2002) pp 589-608
[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.
[DC Types]
DCMI Types, DCMI Usage Board, 18 December 2006.
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)
[Media Fragments]
Media Fragments URI, W3C Working Draft, Troncy, R. Mannens, E (eds), 17 December 2009.
Memento: Time Travel for the Web, Van de Sompel, H, Nelson, M, Sanderson R. October 2010.
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 2854]
The 'text/html' Media Type, Connolly, D. and L. Masinter, RFC 2854, June 2000.
[RFC 3023]
XML Media Types, Murata, M., St. Laurent, S., and D. Kohn, RFC 3023, January 2001.
[RFC 3236]
The 'application/xhtml+xml' Media Type, Baker, M. and P. Stark, RFC 3236, January 2002.
[RFC 3778]
The application/pdf Media Type, Taft, E., Pravetz, J., Zilles, S., and L. Masinter, RFC 3778, May 2004.
[RFC 3986]
Uniform Resource Identifier (URI): Generic Syntax, Berners-Lee, T., Fielding, R., and L. Masinter, STD 66, RFC 3986, January 2005.
[RFC 5147]
URI Fragment Identifiers for the text/plain Media Type, Wilde, E. and M. Duerst, RFC 5147, April 2008.

A. Acknowledgements

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

B. Change Log

Date Editor Description
2010-04-19 rsanderson Internal alpha release
2010-06-30 rsanderson External alpha2 release
2010-10-15 rsanderson External alpha3 release
2011-03-15 tcole added links to additional examples
Creative Commons LicenseThis work by the Open Annotation Collaboration is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.