Abstract

This document provides a single reference point to find commonly used types of Constraint within the Open Annotation framework. The constraints are divided in to sections, based on the type of resource they are constraining and a further section on filtering constraints that convey information about the conditions under which the resource should be considered to be part of the annotation.


Table of Contents

1. Introduction
     1.1 Namespaces Used
2. Constraint Type List
     2.1 Text Resource Constraints
     2.2 Image Resource Constraints
     2.3 Audio Resource Constraints
     2.4 Video Resource Constraints
     2.5 Data Resource Constraints
     2.6 Filtering Constraints

Appendices

A. Acknowledgements
B. Change Log


1. Introduction

This document provides a single reference point to find commonly used types of Constraint within the Open Annotation framework. The constraints are divided in to sections, based on the type of resource they are constraining and a further section on filtering constraints that convey information about the conditions under which the resource should be considered to be part of the annotation.

The constraints listed here can come from any namespace or vocabulary. There is a section in the Open Annotation Wiki for collaboratively developing constraints, prior to announcing them and having them referenced from this document. To request a Constraint be listed, please send a mail to the Open Annotation Google Group

1.1 Namespaces Used

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

Prefix Namespace URI Description
aos http://purl.org/ao/selectors/ Annotation Ontology Selectors
cnt http://www.w3.org/2008/content# Content in RDF
dc http://purl.org/dc/elements/1.1/ Dublin Core elements
dcterms http://purl.org/dc/terms/ Dublin Core terms
dcmitypes http://purl.org/dc/dcmitype/ Dublin Core types
foaf http://xmlns.com/foaf/0.1/ Friend of a Friend vocabulary
oac http://www.openannotation.org/ns/ OAC vocabulary
rdf http://www.w3.org/1999/02/22-rdf-syntax-ns# RDF vocabulary
rdfs http://www.w3.org/2001/01/rdf-schema# RDF Schema vocabulary

2. Constraint Type List

In order to describe segments of resources, or otherwise constrain the applicability of an Annotation on a Target or Body, it is sometimes necessary to use a Constraint. This document collects the known Constraint subClasses together to promote re-use and consistency.

For reference, the Constraint data model is replicated below.

Figure 1: Constraint Model

2.1 Text Resource Constraints

2.1.1 OffsetRangeConstraint

Any sublist of an ordered list of characters can be selected by an starting at a particular point in the stream and reading forwards for a number of characters. For example, characters 20 through 30 of a text document start at an offset of 20, and then read forwards for a range of 10 characters to get to character 30. Thus, if the document were "abcdefghijklmnopqrstuvwxyz" and the start were 5, and the range 3, the selection would be "efg".

The use of this constraint does not require text to be copied into the constraint, unlike the PrefixSuffixConstraint below, but is very brittle with regards to changes to the resource. Any edits may change the selection, and thus it is also recommended that either oac:when or a TimeConstraint be used as well.

Ontology

We define a new class, oac:OffsetRangeConstraint, and use two terms from the Annotation Ontology's equivalent Selector:

oac:OffsetRangeConstraint
A Constraint for text that defines its selection in terms of a starting point within the document and a number of characters from that point.
aos:offset
The number of characters into the document from which to start the selection, the first character being character 1.
aos:range
The number of characters in the selection, including the start character.

2.1.2 PrefixPostfixConstraint

This constraint selects a range of text by copying it exactly, and including some range of text immediately before and after it to distinguish between multiple copies of the same texts within the resource. The specific length of the prefix and suffix should be determined from the context of the document.

For example, if the document were again "abcdefghijklmnopqrstuvwxyz", one could select "efg" by an aos:prefix of "abc", an aos:exact of "efg" and an aos:postfix of "hijk".

Ontology

We define a new class, oac:PrefixPostfixConstraint, and use three terms from Annotation Ontology:

oac:PrefixPostfixConstraint
A Constraint for text that defines its selection in terms of the desired text, and a range of text before and after it.
aos:prefix
The text immediately preceding the selected text.
aos:exact
The selected text itself
aos:postfix
The text immediately following the selected text.

2.2 Image Resource Constraints

2.2.1 SvgConstraint

An SvgConstraint defines a section of an image (or other two dimensional resource) through the Scalable Vector Graphics (SVG) standard. The content of the SvgConstraint, either embedded within the Annotation using ContentAsText or as an HTTP derefencable resource, should be a single SVG element, not an entire SVG canvas. The shape element should be one of: path, rect, circle, ellipse, line, polyline, polygon. The 'g' element may also be used, if and only if necessary, to construct a multi-element group. For example, a donut shape requires an outer circle and a clipped inner circle.

The dimensions of the shape must be relative to the dimensions of the constrained Image. For example, if the Image is 600 pixels wide and 400 pixels high, and the desired section is a circle of 100 pixel radius in the center of the image, then the element would be: <circle cx="300" cy="200" r="100"/>

It is possible to include style information in the SVG element, however implementers should be aware that even if SvgConstraints are supported by consuming clients, they may not recognise the style. Javascript, animation, text and other possible components within the SVG are strongly discouraged.

Ontology

We only need to define a new class:

oac:SvgConstraint
A Constraint that, when dereferenced, provides an SVG XML element that should be overlaid on an Image to define the region of interest

2.3 Audio Resource Constraints

No audio constraints are known to date.

2.4 Video Resource Constraints

No video constraints are known to date.

2.5 Data Resource Constraints

No data constraints are known to date.

2.6 Filtering Constraints

2.6.1 WebTimeConstraint

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. In order to specify the time at which a particular resource should be considered for the purposes of the Annotation, we need a WebTimeConstraint that records the timestamp to be applied.

For more details about time and annotation, see section 3.8 of the main Open Annotation Guidelines document.

Ontology

We define a new class and a new property:

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.

2.6.2 ContextConstraint

Annotations might only apply to a resource when it is being used in the context of one or more other resources. For example, one might wish to annotate an image as it appears within a web page, to say that it is in the wrong place. This is only true of the image within the context of the web page, not in general. In order to accommodate this, we define a ContextConstraint which records the context resource in which the target resource should be considered.

Ontology

We only need to define a new class and a new property:

oac:ContextConstraint
A Constraint that selects the resource only in the context of the target of oac:inContextOf
oac:inContextOf
The context resource

A. Acknowledgements

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

B. Change Log

Date Editor Description
2011-08-10 rsanderson Initial (beta) release
 
Creative Commons LicenseThis work by the Open Annotation Collaboration is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.