Open Annotation Data Model Module: Multiplicity ConstructsCommunity Draft, 08 February 2013 |
Open Annotation Data Model Module: Multiplicity ConstructsCommunity Draft, 08 February 2013 |
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.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 Item Type Description oa:item Relationship [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 Item Type Description oa:Choice Class [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:default Relationship [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.
<anno1> a oa:Annotation ;
oa:hasBody <choice1> ;
oa:hasTarget <target1> .
<choice1> a oa:Choice ;
oa:default <body1> ;
oa:item <body2> .
SELECT ?anno WHERE { ?anno oa:hasBody ?body . ?body a oa:Choice .
?body oa:default ?default }
=> <anno1>
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 Item Type Description oa:Composite Class [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.
<anno1> a oa:Annotation ;
oa:hasBody <body1> ;
oa:hasTarget <comp1> .
<comp1> a oa:Composite ;
oa:item <target1> ;
oa:item <target2> .
SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:Composite .
?target oa:item <Target1> }
=> <anno1>
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.
oa:item statements from the rdf:first, rdf:rest pattern could be:
rdf:first rdfs:subPropertyOf oa:item .
oa:item owl:propertyChainAxiom ( rdf:rest oa:item ) .
Vocabulary Item Type Description oa:List Class [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:List Class An rdf:List is a resource that can be used to build descriptions of ordered lists and other list-like structures. rdf:first Relationship The first resource in a particular list, the remainder being referenced by rdf:rest. rdf:rest Relationship Either an instance of rdf:List, or rdf:nil if there are no further items in the list. rdf:nil Resource A particular instance of rdf:List that represents the empty 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> ) .
SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource .
?target oa:hasSelector ?list . ?list a oa:List }
=> <anno1>