2. Classes

RDF has a very strong notion of classes and instantiation of classes, and as such this notion is widely used to convey information to consuming clients as to the overall nature of a resource. The Open Annotation model requires classes on all of its consitituent resources. This section lists a series of recommendations regarding classes to use when not prescribed by the core model.

2.1. Annotation Classes

In many cases it is important to understand the reasons why the Annotation was created. Open Annotation uses subClasses of the oa:Annotation class to model these reasons, and example instances of it might include Comment, Moderation, Reply, or Link.

It is RECOMMENDED that, if the class does not come from the set of Classes listed below, then the oa:Annotation class be explicitly provided to ensure that consuming clients are aware that the resource is an Open Annotation.

Model

Vocabulary Item	Type	Description
oax:Bookmark	Class	[subClass of oa:Annotation] The class for an Annotation that represents a bookmark to the target resources or recorded point or points within one or more resources. Bookmarks may or may not have a Body resource
oax:Change	Class	[subClass of oa:Annotation] The class for an Annotation that represents a request for a modification or edit to the target resource
oax:Classification	Class	[subClass of oa:Annotation] The class for an Annotation that represents the assignment of a classification type, typically from a controlled vocabulary, to the target resource(s)
oax:Comment	Class	[subClass of oa:Annotation] The class for an Annotation that represents a commentary about or review of the target resource(s)
oax:Description	Class	[subClass of oa:Annotation] The class for an Annotation that represents a description of the target resource(s), as opposed to a Comment about them
oax:Highlight	Class	[subClass of oa:Annotation] The class for an Annotation that represents a highlighted section of the target resource or segment. A Highlight may or may not have a Body, and is likely to have both a Selector and a Style
oax:Link	Class	[subClass of oa:Annotation] The class for an Annotation that represents a link (of unspecified semantics) between the body and target resources
oax:Moderation	Class	[subClass of oa:Annotation] The class for an Annotation that represents an assignment of value or quality to the target resource(s)
oax:Question	Class	[subClass of oa:Annotation] The class for an Annotation that represents a question about the target resource(s)
oax:Reference	Class	[subClass of oa:Annotation] The class for an Annotation that represents a reference for the target resource or segment
oax:Reply	Class	[subClass of oa:Annotation] The class for an Annotation that represents a reply to a previous statement, either an Annotation or another resource
oax:Tag	Class	[subClass of oa:Annotation] The class for an Annotation that represents a Tag on the target resource(s). The tagging resource may be of any type or format.

Figure 2.1. Annotation Class Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <Target1> ;
    oa:hasBody <Body1> .

Usage

   SELECT ?anno WHERE { ?anno rdf:type oax:Comment }
=> <Canvas1>

2.2. Resource Classes

The basic type of the resources, such as if it is an Image, Audio or Video file, used as either Body or Target of the Annotation is very useful information to clients. This information prevents the need for classes of Annotation based on this type, and allows consuming clients to determine how to render the resource without maintaining a long list of mime types, or if they should attempt to render it at all.

The Dublin Core Types vocabulary is RECOMMENDED for expressing these classes. The most common classes are listed in the table below. The definitions are summarized from the DCMI types documentation. Please note that the advice of the DCMI to encode images of text as dctypes:Text is NOT RECOMMENDED within the context of Open Annotation, as it does not help consuming clients to interpret or render the resource, such as via HTML5 media elements.

Model

Vocabulary Item	Type	Description
dctypes:Dataset	Class	The class for a resource which encodes data in a defined structure
dctypes:Image	Class	The class for a image resources, primarily intended to be seen
dctypes:MovingImage	Class	The class for a video resources, with or without audio
dctypes:Sound	Class	The class for a resource primarily intended to be heard
dctypes:Text	Class	The class for a resource primarily intended to be read

Figure 2.2. Resource Class Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <Target1> ;
    oa:hasBody <Body1> .
    
  <Body1> a dctypes:Text .
  <Target1> a dctypes:Image .

Usage

   SELECT ?anno WHERE { ?anno oa:hasBody ?body ; ?body a dctypes:Text }
=> <Anno1>

2.3. Agents

The provenance of an Annotation is important to capture, as discussed in the Provenance section of the Core specification. This section recommends best practices for recording information about the agents involved in the Annotation, in particular the annotator and generator.

The terms listed below are RECOMMENDED for use in describing agents. Other terms from the FOAF vocabulary are also RECOMMENDED, but not presented explicitly. Other more specific vocabularies MAY also be used as appropriate.

Model

Vocabulary Item	Type	Description
foaf:Person	Class	The class for a human agent, typically used as the class of the object of the oa:annotator relationship
dctypes:Software	Class	The class for a software agent, typically used as the class of the object of the oa:generator relationship
foaf:name	Property	The name of the agent. Each agent SHOULD have exactly 1 name property.
foaf:mbox	Relationship	The email address associated with the agent, using the mailto: URI scheme. Each agent MAY have 1 or more mailboxes
foaf:openid	Relationship	The openId URI associated with the agent. Each agent MAY have 1 or more openIds.

Figure 2.1. Agent Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <Target1> ;
    oa:hasBody <Body1> ;
    oa:annotator <Agent1> ;
    oa:generator <Agent2> .
  
  <Agent1> a foaf:Person ;
    foaf:openid <OpenId1> ;
    foaf:name "Some Person" .
    
  <Agent2> a dctypes:Software ;
    foaf:mbox <MailTo1> ;
    foaf:name "Some Software" .

Usage

   SELECT ?anno WHERE { ?anno oa:annotator ?who ; ?who a foaf:Person }
=> <Anno1>

3.1. States

Currently there are no defined subClasses of the State specifier in the Extension namespace. Future planned subClasses include a means to specify the HTTP headers necessary to retrieve the correct representation, and a subClass to record fixity information such as content digests or checksums to determine if the representation retrieved is the same as the one annotated.

3.2. Selectors

While the FragmentSelector class is good enough to cover many use cases, it is not sufficient for everything. This Extension document defines several further, media-type specific Selectors to fulfil cross-community requirements which are not covered by FragmentSelector.

3.2.1. Text Selection by Offset

Any sublist of an ordered list of characters can be selected by starting at a particular point in the stream and reading forwards for a number of characters. The starting character is included in the selection, and the first character in the list is character 0. It can also be thought of as the position of a pointer into the list, and the number of items to consume. Thus position 0 would be immediately before the first character, in this way of thinking. For example, if the document was "abcdefghijklmnopqrstuvwxyz", the start was 4, and the range was 3, the selection would be "efg".

The text should be normalized to a readable string before counting characters. HTML/XML tags should be removed, character entities should be reduced to the character that they encode, redundant whitespace should be normalized, and so forth. This allows the Selector to be used with different formats and still have the same semantics and utility.

The use of this Selector does not require text to be copied into the Annotation graph, unlike the the Text Selection by Quotation approach, 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 used as well to help identify the correct representation.

Model

Vocabulary Item	Type	Description
oax:TextOffsetSelector	Class	[subClass of oa:Selector] The class for a Selector which describes a range of text based on its starting position (oax:offset) and length (oax:range).
oax:offset	Property	The starting position of the segment of text. The first character in the full text is character position 0. Each TextOffsetSelector MUST have exactly 1 oax:offset property.
oax:range	Property	The length of the segment of text selected. The last character is thus included within the segment. Each TextOffsetSelector MUST have exactly 1 oax:range property.

Figure 3.2.1. Offset Selector Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <SpTarget1> ;
    oa:hasBody <Body1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasSource <Target1> ;
    oa:hasSelector <TextSel1> .
  
  <TextSel1> a oax:TextOffsetSelector ;
    oax:offset 4 ;
    oax:range 3 .
    
  <Target1> a dctypes:Text .

Usage

   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt ; ?spt a oa:SpecificResource ;
            ?spt oa:hasSelector ?txt ; ?txt a oax:TextOffsetSelector ;
            ?txt oax:range ?rng ; FILTER (?rng < 10) }
=> <Anno1>

3.2.2. Text Selection by Quotation

This Selector describes 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 text 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 a prefix of "abcd", the quotation of "efg" and a suffix of "hijk".

The text to be quoted should be normalized to a readable string before recording. Thus HTML/XML tags should be removed, character entities should be reduced to the character that they encode, redundant whitespace should be normalized, and so forth. 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 Offset Selector is perhaps more appropriate.

Model

Vocabulary Item	Type	Description
oax:TextQuoteSelector	Class	[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.
oax:exact	Property	A copy of the text which is being selected, after normalization. Each TextQuoteSelector MUST have exactly 1 oac:exact property.
oax:prefix	Property	A snippet of text that occurs immediately before the text which is being selected. Each TextQuoteSelector SHOULD have exactly 1 oac:prefix property, and MUST NOT have more than 1.
oax:suffix	Property	The snippet of text that occurs immediately after the text which is being selected. Each TextQuoteSelector SHOULD have exactly 1 oac:suffix property, and MUST NOT have more than 1.

Figure 3.2.2. Quotation Selector Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <SpTarget1> ;
    oa:hasBody <Body1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasSource <Target1> ;
    oa:hasSelector <TextSel1> .
  
  <TextSel1> a oax:TextQuoteSelector ;
    oax:exact "efg" ;
    oax:prefix "abcd" ;
    oax:suffix "hijk" .

Usage

   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt ; ?spt a oa:Specific Resource ;
            ?spt oa:hasSelector ?txt ; ?txt a oax:TextQuoteSelector ;
            ?txt oax:exact "efg" }
=> <Anno1>

3.2.3. Area Selection by SVG

An SvgSelector defines an area through the use of the Scalable Vector Graphics standard. The content of the Selector, either embedded as an Inline Specifier or accessible as a dereferencable resource, is a single SVG element; it is RECOMMENDED to embed the element within the Annotation as it is not a valid SVG document by itself. The shape element MUST be one of: path, rect, circle, ellipse, polyline, polygon or g. The g element may 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 the shape 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.

Model

Vocabulary Item	Type	Description
oax:SvgSelector	Class	[subClass of oa:Selector] The class for a Selector which defines a shape using the SVG standard.

Figure 3.2.3. SVG Selector Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <SpTarget1> ;
    oa:hasBody <Body1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasSelector <Svg1> ;
    oa:hasSource <Target1> .
    
  <Svg1> a oax:SvgSelector ;
         a cnt:ContentAsText ;
    cnt:chars "<circle cx="300" cy="200" r="100"/>" .

Usage

   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt ; ?spt a oa:SpecificResource ;
                ?spt oa:hasSelector ?svg ; ?svg a oax:SvgSelector }
=> <Anno1>

3.3. Styles

3.3.1. CSS Value 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.

The Style class in the Open Annotation model for CSS uses only the value part of the CSS, typically a block of definitions enclosed in {} characters. The ruleset selector (typically the name of the element, its class or id) is not used, as this would restrict implementation choice of naming conventions. For example, if the border of the selection should be colored red, the representation of the Style resource would be: {border: 1px solid red}

As the content is not a valid CSS document, it is RECOMMENDED that it be embedded within the Annotation, unless it is intended for use by multiple Annotations.

The exact rendering of the Specific Body or Target is, ultimately, up to the user's client. The use of this Style in Open Annotation does not preclude non-HTML based clients, but it must be expected that such clients will not process all, or even any, of the styling hints provided in the CSS Value Style.

Model

Vocabulary Item	Type	Description
oax:CssValueStyle	Class	[subClass of oa:Style] The class for representing CSS styling information for Specific Resources

Figure 3.3.1. CSS Value Style Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <SpTarget1> ;
    oa:hasBody <Body1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasStyle <Css1> ;
    oa:hasSource <Target1> .
    
  <Css1> a oax:CssValueStyle ;
         a cnt:ContentAsText ;
    cnt:chars "{border: 1px solid red}" .

Usage

   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt ; ?spt a oa:SpecificResource ;
            ?spt oa:hasStyle ?style ; ?style a oax:CssValueStyle }
=> <Anno1>

3.3.2. XSLT Style

Resources encoded in XML can be transformed into other formats or schemas using Extensible Stylesheet Language Transformations (XSLT). Using XSLT, a single resource could encode a machine readable version of the information to be conveyed, and a client can still display a customized human readable version after the transformation.

After retrieving the representation of the Source resource, potentially applying a Selector to extract a segment of it, the client SHOULD then apply the transformations specified in the XSLT to the representation or segment. The format of the representation SHOULD therefore be XML, so attention MUST be paid to any State Specifiers that describe how to retrieve the correct representation.

It is RECOMMENDED that, unlike CSS Value Styles, XSLT Styles should be unique dereferencable resources rather than embedded within the Annotation. This is due to the size of the XSLT stylesheet, and that it is a full document conforming to the XSLT specification.

Model

Vocabulary Item	Type	Description
oax:XsltStyle	Class	[subClass of oa:Style] The class for representing an XSLT Stylesheet to be applied to an XML representation of a resource

Figure 3.3.2. XSLT Style Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <SpTarget1> ;
    oa:hasBody <Body1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasStyle <Xslt1> ;
    oa:hasSource <Target1> .
    
  <Xslt1> a oax:XsltStyle .
  
  <Target1> a dctypes:Text ;
    dc:format "text/xml" .

Usage

   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt ; ?spt a oa:SpecificResource ;
            ?spt oa:hasStyle ?style ; ?style a oax:XsltStyle}
=> <Anno1>

3.4. Composite Specifiers

The Core Open Annotation model specifies the interpretation for multiple Specifiers attached to the same Specific Resource as being alternatives. This allows for a choice between a set of alternatives, but not the composition of multiple Specifiers such that all must be taken into account. Allowing the composition of multiple specifiers would cover use cases such as non-rectangular sections of a Video resource, described using an oax:SvgSelector at a particular point in the video, encoded using a media fragment in a oa:FragmentSelector. The Open Annotation Extension model defines three Composite Specifiers, one for each type of Specifier, to fulfil such use cases.

The interpretation of oa:hasState, oa:hasSelector and oa:hasStyle when the subject resource is a Composite Specifier is that ALL of the object Specifiers must be processed. The order in which the Specifiers are processed is left up to either further subClasses or the consuming client to determine. In some cases this will not matter, such as selecting the area of the video and then the time or vice versa, and in other cases it will be very important; an XSLT Style must come before a CSS Value Style to result in the correct rendering, for example.

Please Note that while oax:CompositeSelector is used in the example below, the other Composite classes follow exactly the same pattern.

Model

Vocabulary Item	Type	Description
oax:CompositeState	Class	[subClass of oa:State] The class for a State which encapsulates more than one other State which must be processed.
oax:CompositeSelector	Class	[subClass of oa:Selector] The class for a Selector which encapsulates more than one other Selector which must be processed.
oax:CompositeStyle	Class	[subClass of oa:Style] The class for a Style which encapsulates more than one other Style which must be processed.

Figure 3.4. Composite Specifier Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <SpTarget1> ;
    oa:hasBody <Body1> .
    
  <SpTarget1> a oa:SpecificResource ;
    oa:hasSelector <Comp1> ;
    oa:hasSource <Target1> .
    
  <Comp1> a oax:CompositeSelector ;
    oa:hasSelector <Selector1> ;
    oa:hasSelector <Selector2> .

Usage

   SELECT ?anno WHERE { ?anno oa:hasTarget ?spt ; ?spt a oa:SpecificTarget ;
            ?spt oa:hasSelector ?comp ; ?comp a oax:CompositeSelector ;
            ?comp oa:hasSelector <Selector1> }
=> <Anno1>

  SELECT ?target WHERE { ?anno oax:hasSemanticTag <Tag1> . ?anno oa:hasTarget ?target }
=> <Target1>

  SELECT ?anno, ?what WHERE { ?anno oa:hasBody ?g . ?anno oa:hasTarget ?t .
           GRAPH ?g { ?t relationship ?what } }
  }
=> <Anno1>, <Thing1>

4.3. Structured Resources

It is desirable to facilitate more complex structures than a simple tag, without requiring the use of Named Graphs and specific serializations. For example, an RDFa serialization could not encode the structure described in the previous sub-section. In order to accomplish this, the Open Annotation Extension model allows for arbitrary graph structures to be included, and used in the role of Body or Target. The identifier MUST NOT be dereferencable; if it is, then the information SHOULD be available from the dereferencable resource like any other representation.

The use of this approach is NOT RECOMMENDED when cross-community interoperability is important, as the structures are unlikely to be correctly processed without prior knowledge. Further considerations include:

• Implementations that expect a resource with a serialization separate from the Annotation graph may not be able to store structured resources
• The agent responsibe for asserting the triples in the structure is assumed to be the oa:annotator, but this may not be correct

Model

Figure 4.3. Structured Resource Model

  <Anno1> a oax:Comment ;
    oa:hasTarget <Target1> ;
    oa:hasBody <Struct1> .
    
  <Struct1> c <X> .

  <X> b <Y> ;
    b <Z> .
    
  <Z> a 123 .

Usage

  SELECT ?anno WHERE { ?anno oa:hasBody ?sb ; ?sb c <X> ; <X> b <Y> }
=> <Anno1>