Open Annotation: Constraint Type List

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.

1. Introduction

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