W3C Community Draft
previous   contents   next


The OA Community Group's February 2013 Open Annotation Data Model (this document) has been superseded the following W3C Web Annotation Working Group Candiate Recommendations (July 2016):

Implementers are encouraged to begin using the newer specifications as soon as practicable.

Table of Contents

  1. Module: Multiplicity Constructs
    1. Choice
    2. Composite
    3. List

Module: Multiplicity Constructs

There are many use cases where an Annotation comprises multiple Bodies, Targets or both. The semantics defined in the Core for multiple Bodies and Targets are that each resource is related to the others individually, however this is not always the case. It is useful to associate the Annotation with one resource from a group of alternatives, for example to have a comment that is available in three different languages and for the user's client to display only the most appropriate one. Or to annotate a set of resources where all of the resources are equally important, as is the case when comparing resources with each other. In this case, the comment does not apply individually to the resources, it applies to all of them together. Finally, it is useful to consider ordering that set of resources, particularly for grouping Selectors that must be processed in the correct sequence to extract the intended segment.

The Open Annotation model includes three multiplicity constructs to model these requirements: oa:Choice, oa:Composite and oa:List respectively. These nodes are used as the object of the oa:hasBody, oa:hasTarget, oa:hasSelector, oa:hasState, oa:styledBy and oa:hasScope relationships, and refer in turn to their constituent resources using the oa:item relationship. The items may either be resources or further such constructions of multiple resources. For example, a Composite may have two items, one of which is a resource and the other an oa:Choice between two further resources.

Multiplicity Constructs SHOULD have a globally unique URI to identify them, such as a UUID URN. The URI MAY be resolvable, and if it is then the RDF description of the construct, as in the Annotation's graph, MUST be returned when it is dereferenced. This identity recommendation is not typical for the equivalent classes of rdf:Alt, rdf:Bag and rdf:List, and further processing and modeling requirements based on those classes could not be asserted. The Constructs MAY instead be modeled using RDF blank nodes if it is not considered important that they be referenced directly by other Annotations or systems.

Note Well: All of the examples below display only a single construction at a single level, however the same patterns follow for all of the relationships and structures composed of more than one grouping resource.


Vocabulary ItemTypeDescription
oa:itemRelationship[subProperty of rdfs:member] The relationship between a multiplicity construct node and its constituent resources.
There MUST be 1 or more item relationships for each multiplicity construct.


A Choice is a set of resources from which an application that is consuming the Annotation should select only one to process or display. For Specifiers, the Client should choose one of the constituent resources to use, as they are somehow comparable or equivalent. Clients MAY use any algorithm to determine which resource to choose, and SHOULD make use of the information present in the Annotation to do so automatically, or MAY present a list and require the user to make the decision.

The Choice SHOULD have a default option. This is the constituent resource that the Annotation's publisher recommends to be used if the client does not have a preference of its own. This feature should especially be used to express a preferred Selector or State. Note that rdf:Alt does not have an equivalent property.


Vocabulary ItemTypeDescription
oa:ChoiceClass[subClass of rdf:Alt] A multiplicity construct that conveys to a consuming application that it should select one of the constituent resources to display to the user, and not render all of them. This construct is equivalent to the rdf:Alt container class.
oa:defaultRelationship[subProperty of oa:item] The constituent resource to use as a default option, if there is no other means to determine which would be most appropriate.
There SHOULD be exactly 1 default relationship for each Choice.

Figure 4.1 Choice
  <anno1> a oa:Annotation ;
    oa:hasBody <choice1> ;
    oa:hasTarget <target1> .
  <choice1> a oa:Choice ;
    oa:default <body1> ;
    oa:item <body2> .


Query: Find annotations where the body is a Choice of resources with a default.
  SELECT ?anno WHERE { ?anno oa:hasBody ?body . ?body a oa:Choice . 
    ?body oa:default ?default }
=> <anno1>

See Further Examples


A Composite is a set of resources that are all required for an Annotation to be correctly interpreted. Examples include an Annotation that compares the differences between two resources, or an Annotation where the Body consists of both a human readable review and a necessary structured data file. These are different from individual bodies and targets, as each would individually annotate or be annotated. It is also important to be able to combine Specifiers, such as using two Selectors where one gives the time range in a video, and a second gives a non-rectangular area to plot over that time range.

The data model defines a class oa:Composite, and then uses the oa:item relationship defined above. Each Composite MUST have two or more constituent resources, and as all are required there is no default.


Vocabulary ItemTypeDescription
oa:CompositeClass[subClass of rdf:Bag] A multiplicity construct that conveys to a consuming application that all of the constituent resources are required for the Annotation to be correctly interpreted. This construct is equivalent to the RDF container class rdf:Bag.

Figure 4.2 Composite
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <comp1> .
  <comp1> a oa:Composite ;
    oa:item <target1> ;
    oa:item <target2> .


Query: Find annotations where the target is a Composite that includes a particular resource.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:Composite . 
    ?target oa:item <Target1> }
=> <anno1>

See Further Examples


A List is a Composite that also provides an order to its constituent resources in the context of the Annotation. Examples of use are particularly strong for Selectors, where a processing application must first make one selection then another, and if it did it in the other order, the result would be incorrect. This includes situations like first referencing a particular page in a book that does not have its own URI, and then doing a text selection within that page. Another use case would be to assign order to a set of Styles to give precedence to the definition of classes within them.

The order should be provided using the rdf:List construction, and the oa:List resource is at the same time an rdf:List with rdf:first and rdf:rest relationships. The resources should be processed in the order given. Serialization formats have different methods of representing lists that hide the complexity depicted in the diagram below.

Annotation producers SHOULD provide both oa:item and the list predicates. This allows consuming clients to fall back to processing the list in an unordered fashion without iterating through the linked list construction.

At the time of publication there is ongoing discussion in the RDF community in general regarding alternative methods for expressing order. Ordering is inherently problematic in graph structures, and should the underlying specifications change, then the above ordering recommendation may also change. This is one of the reasons for the dual-classing of the resource with both oa:List and rdf:List, in order to maintain some consistency via this specification's class if rdf:List should become deprecated. Further, systems that process rdf:Lists will likely not process the items unless it is explicitly declared.

An algorithm to automatically derive oa:item statements from the rdf:first, rdf:rest pattern could be:
  1. Create a statement [l oa:item i .] for every statement [l rdf:first i .] .
  2. Create a statement [l oa:item i .] for every chain of statements [l rdf:rest r . r oa:item i .] until no new statement can be created.
The following axioms reflect the intended algorithm but may not be valid in OWL2(-DL):
    rdf:first rdfs:subPropertyOf oa:item .
    oa:item owl:propertyChainAxiom  ( rdf:rest  oa:item ) .


Vocabulary ItemTypeDescription
oa:ListClass[subClass of oa:Composite] A multiplicity construct that conveys to a consuming application that all of the constituent resources are required for the Annotation to be correctly interpreted, and in a particular order.
rdf:ListClass An rdf:List is a resource that can be used to build descriptions of ordered lists and other list-like structures.
rdf:firstRelationship The first resource in a particular list, the remainder being referenced by rdf:rest.
rdf:restRelationshipEither an instance of rdf:List, or rdf:nil if there are no further items in the list.
rdf:nilResourceA particular instance of rdf:List that represents the empty list.

Figure 4.3 List
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .
  <sptarget1> a oa:SpecificResource ;
    oa:hasSource <source1> ;
    oa:hasSelector <list1> .

  <list1> a oa:List, rdf:List ;
    oa:item <selector1>, <selector2> ;
    rdf:first <selector1> ;
    rdf:rest ( <selector2> ) .


Query: Find annotations where the target segment requires multiple selectors in order.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource . 
    ?target oa:hasSelector ?list . ?list a oa:List }
=> <anno1>

See Further Examples

previous   contents   next