W3C Community Draft
previous   contents   next

Table of Contents

  1. Module: Specifiers and Specific Resources
    1. Specifiers and Specific Resources
    2. Selectors
      1. Fragment Selector
      2. Range Selectors
        1. Text Position Selector
        2. Text Quote Selector
        3. Data Position Selector
      3. Area Selectors
        1. SVG Selector
    3. States
      1. Time State
      2. Request Header State
    4. Styles
      1. CSS Style
    5. Scope of a Resource

Module: Specifiers and Specific Resources

While it is possible using only the constructions in the core data model to create Annotations that reference parts of resources by using fragment URIs, there are many situations when this is not sufficient. For example, even a simple circular region of an image, or a diagonal line across it, is not possible. Selecting an arbitrary span of text in an HTML page, perhaps the simplest annotation concept, is also not supported by fragment URIs. This module of the specification introduces methods to identify and describe a segment of interest, how to obtain the correct representation of a resource, how to associate style information with an Annotation, and provide scoping information for the Body and Target resources specific to the Annotation.

Specifiers and Specific Resources

Specifiers in the Open Annotation model are used to describe the contextual details of the resources that the Annotation refers to. This could be by describing a particular segment of a resource, the applicable timestamp of a resource which frequently changes, or by providing style information for rendering. In order to ensure that the segments have an identity that can be globally referenced, the model introduces a Specific Resource class that is used to identify the resource, typically a segment, described by the Specifiers.

Specifiers are associated directly with each Specific Resource, which takes the role of either Body or Target in the Annotation. In this context, the full resource is called the Source resource, and thus the Specifier describes how to determine the aspects of the Source that constitute the Specific Resource. For example, a circular area of an image is identified by the Specific Resource, described by a Specifier, and the complete image resource is the Source. The properties and relationships that can be expressed about Body and Target resources, such as type, format and provenance, should remain attached to the Source resource.

The Open Annotation Model defines two primary Specifier classes with different roles: oa:State and oa:Selector. A State describes how to determine the correct representation of the Source resource, and a Selector describes how to discover the correct segment of that representation. The Specific Resource may also have rendering information, associated with it via a Style, and information regarding other resources that provide a more definite scope for the resource, such as its appearance within another resource.

It is expected that if a State is present, it will be processed first to ensure the correct representation is retrieved. Then, if there is a Selector, it would be applied to determine the correct segment of the representation. Finally, if there is a Style, it would be applied to ensure the correct rendering or the resource or segment. As Scopes do not affect the rendering directly, they may be processed in any way deemed appropriate for the user interface or application.

States, Selectors and Styles are intended to be reusable by multiple Annotations, and are thus not linked directly to the Source resource. For example, an instance of a Selector MAY be re-used to select the same segment of multiple resources, or an instance of a State MAY be re-used to ensure a consistent time or set of HTTP request headers. The Specific Resource MAY also be re-used if the information associated with it is applicable in the new context, including any States, Selectors, Styles and Scopes.

The Specifier's description MAY be conveyed as an external or embedded resource, or as RDF properties within the graph. The description SHOULD use existing standards whenever possible. If the Specifier has an HTTP URI, then its description, and only its description, MUST be returned when the URI is dereferenced.

If the Specific Resource has an HTTP URI, then the exact segment of the Source resource that it identifies, and only the segment, MUST be returned when the URI is dereferenced. For example, if the segment of interest is a region of an image and the Specific Resource has an HTTP URI, then dereferencing it MUST return the selected region of the image as it was at the time when the annotation was created. Typically this would be a burden to support, and thus the Specific Resource SHOULD be identified by a globally unique URI, such as a UUID URN. If it is not considered important to allow other Annotations or systems to refer to the Specific Resource, then a blank node MAY be used instead.

Note Well: The same Specifier classes are used for both Specific Target and Specific Body. The diagrams in this module only depict one of these, however the same model applies for both.

Model

Vocabulary ItemTypeDescription
oa:SpecificResourceClassThe class for Specific Resources
The oa:SpecificResource class SHOULD be associated with a Specific Resource to be clear as to its role as a more specific region or state of another resource.
oa:hasSourceRelationshipThe relationship between a Specific Resource and the resource that it is a more specific representation of.
There MUST be exactly 1 oa:hasSource relationship associated with a Specific Resource.

Figure 3.1.2. Specific Resources
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .

  <sptarget1> a oa:SpecificResource ;
    oa:hasSource <source1> .

Usage

Query: Find Annotations which target a particular representation.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource }
=> <anno1>

Selectors

Many Annotations refer to part of a resource, rather than all of it, as the Target. Examples include Annotations on an area within an image or video, a range of characters in text, a time segment in an audio file or a slice of a dataset. Equally, the segment may be the Body of the Annotation, where the comment is given at a particular point in the video, or in a particular paragraph of text.

A Selector is a Specifier which describes how to determine the segment of interest from within the retrieved representation of the Source resource. The nature of the Selector will be dependent on the type of the representation for which the segment is conveyed. For example the methods used to describe a section of an image will be very different to the methods used to discover the correct paragraph of text, or the correct slice of a dataset.

Only one Selector can be associated with a Specific Resource. If multiple Selectors are required, either to express a choice between different optional, equivalent selectors, or a chain of selectors that should all be processed, it is necessary to use the constructions described in the Multiplicity module.

Typically if all of the information needed to resolve the Selector (or other Specifier) is present within the graph, such as is the case for the FragmentSelector, TextQuoteSelector, TextPositionSelector and DataPositionSelector classes, then there is no need to have a resolvable resource that provides the same information. However for the SvgSelector any other specifiers that have a representation with a life of its own, it may be easier or more efficient to have the SVG document resolvable separately from the Annotation via an HTTP URI.

It must also be noted that the model allows several equivalent expressions of the same segment of interest. For example, to describe a rectangular area, it is possible to use URIs with fragments directly (as in the Core document), the FragmentSelector class, or the SvgSelector. Similarly for plain text documents, either RFC 5147 or the Text Selectors could be used. While this is not optimal from an interoperability perspective, this could not be avoided at the same time as keeping the Open Annotation model flexible and compatible with existing specifications. It is RECOMMENDED that communities implement shared bridging strategies and follow the recommendations of the specification and any best practice documents wherever possible.

Model

Vocabulary ItemTypeDescription
oa:SelectorClassThe super class for individual Selectors. This class is not used directly in Annotations, only its subclasses are.
oa:hasSelectorRelationshipThe relationship between a Specific Resource and a Selector.
There MUST be exactly 0 or 1 oa:hasSelector relationship associated with a Specific Resource.

Figure 3.2. Selector
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .

  <sptarget1> a oa:SpecificResource ;
    oa:hasSource <source1> ;
    oa:hasSelector <selector1> .

Usage

Query: Find annotations about any part of a resource.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource . 
    ?target oa:hasSelector ?select }
=> <anno1>

Fragment Selector

The web architecture defines a method of identifying a particular segment of a resource, using the fragment part of the URI. This has been used for media type specific fragments (such as XML and PDF) and more recently for media fragments that are applicable to entire classes of resources, such as Image and Video, regardless of their exact media type.

The Open Annotation model defines a fragment-based Selector (oa:FragmentSelector) which allows both existing and future fragment specifications to be used to describe the segment of interest. The description of the segment is the syntax for the fragment identifier component of the URI, and it is included in the Annotation graph via the rdf:value property. Thus a fragment URI may be reconstructed by concatenating the oa:hasSource resource's URI, plus a '#', plus the value. For example, if the resource's URI was http://www.example.com/image.jpg and the rdf:value property was "xywh=1,2,3,4", then the resulting URI would be http://www.example.com/image.jpg#xywh=1,2,3,4.

It is RECOMMENDED to use oa:FragmentSelector rather than annotating the fragment URI directly, as expressed in the Core, although consuming applications MUST be aware of both. Publishing systems MAY rewrite fragment URIs into the corresponding oa:FragmentSelector form.

Clients MUST process the value of the FragmentSelector based on the standard that it conforms to, expressed using the dcterms:conformsTo relationship. If that is not present, then the client should use the media type of the Source resource to determine the meaning of the fragment. This is to prevent misinterpretation of the fragment identifier component, which is by definition media type dependent. For example, it is possible to construct a fragment identifier that looks like it conforms to the W3C Media Fragment specification as part of an HTML anchor (for example, #xywh=1,2,3,4 also refers to this section of this HTML document, not a 3 by 4 pixel area, starting at 1,2). Clients MUST therefore also use any State information provided to be certain that the representation appropriate for the FragmentSelector is retrieved.

Model

Vocabulary ItemTypeDescription
oa:FragmentSelectorClass[subClass of oa:Selector] A resource which describes the segment of interest in a representation, through the use of the fragment identifier component of a URI.
rdf:valuePropertyThe contents of the fragment identifier component of a URI that describes the segment of interest in the resource.
The oa:FragmentSelector MUST have exactly 1 rdf:value property.
dcterms:conformsToRelationshipThe Fragment Selector SHOULD have a dcterms:conformsTo relationship with the object being the specification that defines the syntax of the fragment.

URIs used to identify fragment specifications:

Fragment SpecificationDescription
http://tools.ietf.org/rfc/rfc3236XHTML, and HTML. Example: #namedSection
http://tools.ietf.org/rfc/rfc3778PDF. Example: #page=10&viewrect=50,50,640,480
http://tools.ietf.org/rfc/rfc5147Plain Text. Example: #char=0,10
http://tools.ietf.org/rfc/rfc3023XML. Example: #xpointer(/a/b/c)
http://www.ietf.org/rfc/rfc3870RDF/XML. Example: #namedResource
http://www.w3.org/TR/media-frags/W3C Media Fragments. Example: #xywh=50,50,640,480
http://www.w3.org/TR/SVG/SVG. Example: #svgView(viewBox(50,50,640,480))

Figure 3.2.1. Fragment Selector
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .
    
  <sptarget1> a oa:SpecificResource ;
    oa:hasSelector <selector1> ;
    oa:hasSource <source1> .
    
  <selector1> a oa:FragmentSelector ;
    dcterms:conformsTo <spec1> ;
    rdf:value "namedSection" .

Usage

Query: Find annotations where the segment of interest could be described by the fragment component of a URI.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource . 
    ?target oa:hasSelector ?select . ?select a oa:FragmentSelector .
    ?select rdf:value "fragment1" }
=> <anno1>

See Further Examples

Range Selectors

There are several selectors that describe how to extract segments that have a start and end in linear data, such as extracting characters from text or bytes from data. Range selectors are also used to describe points within linear data, for example a cursor location for where to insert information into a web page. This is done by giving a 0 length selection.

Three Range Selectors are defined by the model, two for text and one for bitstreams.

Text Position Selector

Any sublist of an ordered list of characters can be selected by starting at a particular point in the stream and reading forwards until an end point. The start can be thought of as the position of a cursor in the list. Position 0 would be immediately before the first character, position 1 would be immediately before the second character, and so on. The start character is thus included in the list, but the end character is not as the cursor stops immediately before it.
For example, if the document was "abcdefghijklmnopqrstuvwxyz", the start was 4, and the end was 7, then the selection would be "efg".

The text MUST be normalized before counting characters. HTML/XML tags should be removed, character entities should be replaced with the character that they encode, unnecessary whitespace should be normalized, and so forth. The normalization routine may be performed automatically by a browser, and other clients should implement the DOM String Comparisons method. This allows the Selector to be used with different formats and still have the same semantics and utility. For a Selector that works from the bitstream rather than the rendered characters, please see the Data Position Selector.

The use of this Selector does not require text to be copied from the Source document into the Annotation graph, unlike the Text Quote Selector, but is very brittle with regards to changes to the resource. Any edits may change the selection, and thus it is RECOMMENDED that a State be additionally used to help identify the correct representation.

Model

Vocabulary ItemTypeDescription
oa:TextPositionSelectorClass[subClass of oa:Selector] The class for a Selector which describes a range of text based on its start and end positions.
oa:startPropertyThe starting position of the segment of text. The first character in the full text is character position 0, and the character is included within the segment.
Each TextPositionSelector MUST have exactly 1 oa:start property.
oa:endPropertyThe end position of the segment of text. The last character is not included within the segment.
Each TextPositionSelector MUST have exactly 1 oa:end property.

Figure 3.2.2.1. Text Position Selector
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .
    
  <sptarget1> a oa:SpecificResource ;
    oa:hasSource <source1> ;
    oa:hasSelector <selector1> .
  
  <selector1> a oa:TextPositionSelector ;
    oa:start 4 ;
    oa:end 7 .

Usage

Query: Find the annotations that target some range of text:
   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt . ?spt a oa:SpecificResource .
            ?spt oa:hasSelector ?txt . ?txt a oa:TextPositionSelector .
            ?txt oa:start ?s ; oa:end ?e . FILTER (?s < 5) .
            FILTER (?e > 6) }
=> <anno1>

Text Quote Selector

This Selector describes a range of text by copying it, and including some range of text immediately before and after it to distinguish between multiple copies of the same sequence of characters within the document. The 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 a prefix of "abcd", the quotation of "efg" and a suffix of "hijk".

The text MUST be normalized before recording. Thus HTML/XML tags should be removed, character entities should be replaced with the character that they encode, unnecessary whitespace should be normalized, and so forth. The normalization routine may be performed automatically by a browser, and other clients should implement the DOM String Comparisons method. This allows the Selector to be used with different encodings and still have the same semantics and utility.

If the content is under copyright, then this method of selecting text is potentially dangerous. A user might select the entire text of the document to annotate, and a client naïvely copy it into the Annotation and publish it openly on the web. For static texts with access and/or distribution restrictions, the use of the Text Position Selector is perhaps more appropriate.

Model

Vocabulary ItemTypeDescription
oa:TextQuoteSelectorClass[subClass of oa:Selector] The class for a Selector that describes a textual segment by means of quoting it, plus passages before or after it.
oa:exactPropertyA copy of the text which is being selected, after normalization.
Each TextQuoteSelector MUST have exactly 1 oa:exact property.
oa:prefixPropertyA snippet of text that occurs immediately before the text which is being selected.
Each TextQuoteSelector SHOULD have exactly 1 oa:prefix property, and MUST NOT have more than 1.
oa:suffixPropertyThe snippet of text that occurs immediately after the text which is being selected.
Each TextQuoteSelector SHOULD have exactly 1 oa:suffix property, and MUST NOT have more than 1.

Figure 3.2.2.2 Quotation Selector Model
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> .
    oa:hasTarget <sptarget1> .
    
  <sptarget1> a oa:SpecificResource ;
    oa:hasSource <source1> ;
    oa:hasSelector <selector1> .
  
  <selector1> a oa:TextQuoteSelector ;
    oa:exact "efg" ;
    oa:prefix "abcd" ;
    oa:suffix "hij" .

Usage

Query: Find the annotations targeting text segments which read "efg":
   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt . ?spt a oa:Specific Resource .
            ?spt oa:hasSelector ?txt . ?txt a oa:TextQuoteSelector .
            ?txt oa:exact "efg" }
=> <anno1>

Data Position Selector

Very similar to the Text Position Selector, the Data Position Selector uses the same properties but works at the byte in bitstream level rather than the character in text level. This is useful, for example, for annotating segments of disk images for forensic purposes, or the part of a stream of data recorded from a sensor.

Model

Vocabulary ItemTypeDescription
oa:DataPositionSelectorClass[subClass of oa:Selector] The class for a Selector which describes a range of data based on its start and end positions within the byte stream.
oa:startPropertyThe starting position of the segment of data. The first byte is character position 0.
Each DataPositionSelector MUST have exactly 1 oa:start property.
oa:endPropertyThe end position of the segment of data. The last character is not included within the segment.
Each DataPositionSelector MUST have exactly 1 oa:end property.

Figure 3.2.2.1. Data Position Selector
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .

    
  <sptarget1> a oa:SpecificResource ;
    oa:hasSource <source1> ;
    oa:hasSelector <selector1> .
  
  <selector1> a oa:DataPositionSelector ;
    oa:start 4096 ;
    oa:end 4104 .

Usage

Query: Find annotations that target some range of a bitstream:
   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt . ?spt a oa:SpecificResource .
            ?spt oa:hasSelector ?data . ?data a oa:DataPositionSelector .
            ?data oa:start ?s ; oa:end ?e . FILTER (?s < 4100) .
            FILTER (?e > 4100) }
=> <anno1>

Area Selectors

Although simple rectangular areas can be described using media fragment selectors, it is often useful to be able to describe circles, ellipses and arbitrary polygons.

SVG Selector

An SvgSelector defines an area through the use of the Scalable Vector Graphics standard. The content of the Selector is a valid SVG document. It is RECOMMENDED that the document contain only a single shape element and that element SHOULD be one of: path, rect, circle, ellipse, polyline, polygon or g. The g element SHOULD ONLY be used to construct a multi-element group, for example to define a donut shape requiring an outer circle and a clipped inner circle.

The dimensions of both the shape and the SVG canvas MUST be relative to the dimensions of the Source resource. For example, given an image which is 600 pixels by 400 pixels, and the desired section is a circle of 100 pixel radius at the center of the image, then the SVG element would be: <circle cx="300" cy="200" r="100"/>

It is NOT RECOMMENDED to include style information within the SVG element, nor Javascript, animation, text or other non shape oriented information. Clients SHOULD ignore such information if present.

Using only this module, it is necessary to have the SVG document as a separate resource. For example, in the diagram below, the resource named "Selector1" might actually have the URI "http://www.example.com/selections/2341.svg", which would return an SVG document when dereferenced. Please see Embedding Resources for how to embed the SvgSelector within the Annotation instead.

Model

Vocabulary ItemTypeDescription
oa:SvgSelectorClass[subClass of oa:Selector] The class for a Selector which defines a shape using the SVG standard.

Figure 3.2.3.1. SVG Selector
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .
    
  <sptarget1> a oa:SpecificResource ;
    oa:hasSelector <selector1> ;
    oa:hasSource <source1> .
    
  <selector1> a oa:SvgSelector .

Usage

Query: Find the annotations with a target that has a segment specified in SVG:
   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt . ?spt a oa:SpecificResource .
                ?spt oa:hasSelector ?svg . ?svg a oa:SvgSelector }
=> <anno1>

States

The State Specifier describes the intended state of a Body or Target resource as applicable to the particular Annotation, and thus gives a consuming client the information needed to retrieve the correct representation of that resource. As web resources change over time, it might include a link to an archived copy of the Source resource, or the timestamp at which the Annotation applies to assist in discovering appropriate archived representations. Resources may have multiple representations in different formats, and the Annotation may only apply to one of them, and thus the State could describe how to retrieve the representation in the correct format directly from the Source. Other facets include fixity or checksum information to determine whether the retrieved representation is the same as the annotated one, whether the resource requires authentication to retrieve, the user-agent string to send to the web server, and so forth.

Consuming clients MUST process a supplied State before processing any supplied Selector or style information.

Model

Vocabulary ItemTypeDescription
oa:StateClassA resource which describes how to retrieve a representation of the Source resource that is appropriate for the Annotation. This class is not used directly in Annotations, only its subclasses are.
oa:hasStateRelationshipThe relationship between a oa:SpecificResource and an oa:State resource.
There MAY be 0 or 1 oa:hasState relationship for each SpecificResource.

Figure 3.3. State
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .
    
  <sptarget1> a oa:SpecificResource ;
    oa:hasState <state1> ;
    oa:hasSource <source1> .

Usage

Query: Find all of the annotations where the comment resource's representation is further specified.
  SELECT ?anno WHERE { ?anno oa:hasBody ?body . ?body a oa:SpecificResource . 
    ?body oa:hasState ?state }
=> <anno1>

See Further Examples

Time State

A Time State specifier records the time at which the resource is appropriate for the Annotation, typically the time that the Annotation was created. Consuming applications can then use that information to discover an appropriate representation of the resource from that time, for example using the Memento protocol. The State may also have a link directly to an appropriate cached or archived copy of the resource's representation from that time.

Model

Vocabulary ItemTypeDescription
oa:TimeStateClassA resource which describes how to retrieve a representation of the Source resource that is temporally appropriate for the Annotation.
oa:whenPropertyThe timestamp at which the Source resource should be interpreted for the Annotation. The timestamp MUST be expressed in the xsd:dateTime format, and SHOULD have a timezone specified.
There MAY be 0 or more oa:when properties per TimeState, but there MUST be at least one of oa:when and oa:cachedSource. If there is more than 1, each gives an alternative timestamp at which the Source may be interpreted.
oa:cachedSourceRelationshipA link to a copy of the Source resource's representation, appropriate for the Annotation.
There MAY be 0 or more oa:cachedSource relationships per TimeState, but there MUST be at least one of oa:cachedSource and oa:when. If there is more than 1, each gives an alternative copy of the representation.

Figure 3.3.1 Time State
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .
    
  <sptarget1> a oa:SpecificResource ;
    oa:hasState <state1> ;
    oa:hasSource <source1> .
    
  <state1> a oa:TimeState ;
    oa:cachedSource <copy1> ;
    oa:when "2012-07-20T13:30:00Z" .

Usage

Query: Find all of the annotations where the target resource's representation is cached somewhere.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource . 
    ?target oa:hasState ?state . ?state a oa:TimeState . ?state oa:cachedSource ?copy }
=> <anno1>

See Further Examples

Request Header State

As there are potentially many representations that can be delivered from a resource with a single URI, and a Specific Resource may only apply to one of them, it is important to be able to record the HTTP Request headers that need to be sent to retrieve the correct representation. The HttpRequestState resource maintains a copy of the headers to be replayed when obtaining the representation.

Model

Vocabulary ItemTypeDescription
oa:HttpRequestStateClassA resource which describes how to retrieve an appropriate representation of the Source resource for the Annotation, based on the HTTP Request headers to send to the server.
rdf:valuePropertyThe HTTP request headers as a single, complete string, exactly as they would appear in an HTTP request.
There MUST be exactly 1 rdf:value property per HTTPRequestState.

Figure 3.3.2 Http Request State
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .
    
  <sptarget1> a oa:SpecificResource ;
    oa:hasState <state1> ;
    oa:hasSource <source1> .
    
  <state1> a oa:HttpRequestState ;
    rdf:value "Accept: text/plain" .

Usage

Query: Find all of the annotations where the target resource's representation should be retrieved by sending specific HTTP request headers
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource . 
    ?target oa:hasState ?state . ?state a oa:HttpRequestState ; rdf:value ?headers }
=> <anno1>

See Further Examples

Styles

The interpretation of a particular Annotation may rely on rendering style being consistent between clients. For example, if the Body refers to the part of an image highlighted in yellow, as compared to the red highlighted part, then these colors need to be maintained. Equally, annotators may convey information via the styling alone, perhaps only to themselves. In order for this implicit information not to be lost between systems, the styling needs to be consistently represented. For example, an annotator may know that green highlights are intended to be referred back to, but that they disagree with sections highlighted in red.

The Style resource is associated with the Annotation itself, and the content of the resource provides the rendering hints about the Annotation's constituent resources. Styles may also require additional information to be added to the Annotation graph for processing. If there are multiple Style resources that must be associated with the Annotation, then the use of the Multiplicity Constructs is RECOMMENDED.

Consuming applications MAY process these instructions, and publishing systems MUST NOT assume that they will be processed; they are only provided as hints rather than requirements. If a client cannot understand or act upon the style, then it MAY continue to render the selection or resource regardless.

Model

Vocabulary ItemTypeDescription
oa:StyleClassA resource which describes the style in which the selection or resource should be rendered. This class is not used directly in Annotations, only its subclasses are.
oa:styledByRelationshipThe relationship between an Annotation and the oa:Style.
There MAY be 0 or 1 styledBy relationships for each Annotation.

Figure 3.4. Style
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <target1> ;
    oa:styledBy <style1> .

Usage

Query: Find all of the annotations for which style information is provided.
  SELECT ?anno WHERE { ?anno oa:styledBy ?style }
=> <anno1>

See Further Examples

CSS Style

The standard style language for the web is the W3C's Cascading Style Sheets (CSS). It promotes the separation of presentation layer and the content layer for HTML and XML structured documents.

CSS is used in the Open Annotation model via the oa:CssStyle subClass of oa:Style. It uses the common approach of class-selectors and the class label is attached to a Specific Resource using the oa:styleClass property. This class label must only be attached to Specific Resources, as it is not universally true that the Source resource has that class.

Each block in the CSS resource has the format:

  .classname { css-value } 
And thus to associate the color red with a Specific Resource that has a class "red", one would use in the CSS:
  .red { color: red } 
And the Specific Resource (spres1) to be styled would have the property in the Annotation's RDF:
 <spres1> oa:styleClass "red" .

When rendering a Specific Resource, consuming applications SHOULD check to see if it has a oa:styleClass property. If it does, then the application SHOULD attempt to locate the appropriate selector in the CSS document, and then apply the css-value block. If a Specific Resource has a styleClass, but no such class is described by a oa:CssStyle attached to the Annotation, then the oa:styleClass MUST be silently ignored.

The CSS resource MAY have its own dereferenceable URI that provides the information. For example, "Style1" in the diagram below might actually have the URI "http://www.example.com/styles/annotations.css". It MAY be embedded within the Annotation using the inline constructions described in Embedding Resources.

It bears repeating that the exact rendering of the Specific Body or Target is, ultimately, up to the user's client. It is understood that not all consuming clients will include CSS parsers, and thus be unable to process the styling information. The use of this Style in Open Annotation does not preclude non-HTML based clients, although implementation may be more difficult even if the information can be parsed. It must be expected that such clients will not process all, or even any, of the styling hints provided in the CSS Style resource.

Model

Vocabulary ItemTypeDescription
oa:CssStyleClass[subClass of oa:Style] A resource which describes styles for resources participating in the Annotation using CSS.
oa:styleClassPropertyThe string name of the class used in the CSS description that should be applied to the Specific Resource.
There MAY be 0 or more styleClass properties on a Specific Resource.

Figure 3.4.1 CSS Style
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> ;
    oa:styledBy <style1> .

  <style1> a oa:CssStyle .

  <sptarget1> a oa:SpecificResource ;
    oa:hasSource <source1> ;
    oa:styleClass "red" .

Usage

Query: Find all of the annotations for which style information is provided for a target using CSS.
  SELECT ?anno WHERE { ?anno oa:styledBy ?style . ?style a oa:CssStyle . 
	?anno oa:hasTarget ?target . ?target a oa:SpecificResource . 
	?target oa:styleClass ?styleclass
}
=> <anno1>

See Further Examples

Scope of a Resource

It is sometimes important for an Annotation to capture the context in which it was made, in terms of the resources that the annotator was viewing or using at the time. For example, it may be important to know that an annotation on a particular image was made in the context of one web page rather than another. This does not imply an assertion that the annotation is only valid for the image in the context of that page, it just records that the page was being viewed. This might also be useful for annotating a resource in the context of a particular collection.

As such scoping information is only true for a particular Annotation, it must be attached to a Specific Resource, and not to the Source directly. This is true even if there is neither a Selector or a State, as other Annotations that refer to the Source would otherwise incorrectly inherit this assertion. The object of the oa:hasScope relationship is the resource that somehow scopes or provides the context for the resource in this Annotation. For example, in the diagram below, the resource named "scope1" could be the webpage "http://www.example.com/index.html", and the Source resource "source1" could be an image "http://www.example.com/images/logo.jpg", where the Body is a comment that it should not be in that page.

Model

Vocabulary ItemTypeDescription
oa:hasScopeRelationshipThe relationship between a Specific Resource and the resource that provides the scope or context for it in this Annotation.
There MAY be 0 or more hasScope relationships for each Specific Resource.

Figure 3.5. Scope
  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <sptarget1> .
    
  <sptarget1> a oa:SpecificResource ;
    oa:hasScope <scope1> ;
    oa:hasSource <source1> .

Usage

Query: Find annotations where the target is scoped by the resource Scope1.
  SELECT ?anno WHERE { ?anno oa:hasTarget ?target . ?target a oa:SpecificResource . 
    ?target oa:hasScope <Scope1> }
=> <anno1>

See Further Examples


previous   contents   next