Typing of Body and Target

Information concerning the general content type (Text, Image, Audio, Video etc) of the Annotation's related resources is useful to applications. This is expressed using typing of the Body and Target resources, and thereby allows the client to easily determine if and how it can render the resource without maintaining a long list of media types. For example, an HTML5 based client can use the information that the Target resource is an image to generate a <img> element with the appropriate src attribute, rather than having to maintain a list of all of the image media types. The creator of the Annotation may also not know the exact media type of the Body or Target, but should at least be able to provide this general class.

The Dublin Core Types vocabulary is RECOMMENDED for expressing this information by means of RDF classes. The most common classes are listed in the table below, but other classes MAY also be used. 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.

There SHOULD be 1 or more content-based classes associated with the Body and Target resources of an Annotation.

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 image resources, primarily intended to be seen
dctypes:MovingImage	Class	The class for 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.1.1. Typing of Body and Target

  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <target1> .

  <body1> a dctypes:Text .
  <target1> a dctypes:Image .

Usage

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

See Further Examples

Embedded Textual Bodies

Some previous annotation systems have used a property with a string literal to represent textual Bodies. However the Open Annotation model employs the W3C's Content in RDF specification for consistency with non-textual Bodies and other types of resources. The Content in RDF specification introduces a resource with the class cnt:ContentAsText to represent the content, and a property cnt:chars to hold the content string itself.

If it is important that the Body have an identity, then it is RECOMMENDED that the cnt:ContentAsText resource be identified with a UUID URI, but other URIs MAY be used. If this is not considered to be important, for example for short personal notes, then an RDF blank node SHOULD be used instead. This pattern reduces the burden for minting and maintaining identifiers when it is not necessary to do so, but makes it impossible for further Annotations or other systems to refer to the Body without a Skolem IRI.

If known, the media type of the body SHOULD be given using the dc:format property, for example to distinguish between embedded comments in plain text versus those encoded in HTML. As above, the dctypes:Text class MAY also be assigned along with the cnt:ContentAsText class, as there could be other uses of cnt:ContentAsText that encode resources with content other than plain text.

This model was chosen over having a literal as the Body directly for the following reasons:

• It would be inconsistent with the rest of the model which allows any resource as a Body or Target, and thus would be a special case just for text in the Body.
• It is not possible to represent a single property in OWL-DL as having a range of either a literal or a resource, and this is considered important for both reasoning and integration with other systems.
• It makes both the JSON-LD serialization and implementation more complex, as the type of the Body would always have to be determined.
• While literals can have their language and datatype associated with them in RDF, there are other aspects of text that are important for interpretation that cannot be associated with a literal. Examples include the media type (text/plain vs text/html), the directionality (right-to-left versus left-to-right), the encoding (utf-8 vs ascii), plus of course metadata such as authorship, date of creation and so forth.
• Given the previous point, the possibility for a resource to encode an embedded textual Body is essential. As the cost of using a blank node is minimal, the consistency of a single method for embedding content is deemed more important than the option of sometimes using a literal.
• As described in the next section, it is important to distinguish textual tags from general comments. This would not be possible with just a literal.

Model

Vocabulary Item	Type	Description
cnt:ContentAsText	Class	A class assigned to the Body for embedding textual resources within the Annotation. This class SHOULD be assigned to the Body, however it can be inferred from the presence of the mandatory cnt:chars property.
cnt:chars	Property	The character sequence of the content. There MUST be exactly 1 cnt:chars property associated with the ContentAsText resource.
dc:format	Property	The media type of the content. There SHOULD be exactly 1 dc:format property associated with the resource.
dc:language	Property	The language of the content, if known. There MAY be 0 or more dc:language properties. Each language SHOULD be expressed as a language tag, as defined by RFC 3066.

Figure 2.1.2. Embedded Textual Body

  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <target1> .
    
  <body1> a cnt:ContentAsText, dctypes:Text ;
    cnt:chars "content" ;
    dc:format "text/plain" .

Usage

  SELECT ?comment WHERE { ?anno oa:hasBody ?body . ?body a dctypes:Text ; cnt:chars ?comment }
=> "content"

See Further Examples

Tags and Semantic Tags

Tagging a resource, either with a short text string or a with a URI, is a common use case for Annotation. Tags are typically keywords or labels, and used for organization, description or discovery of the resource being tagged. In the Semantic Web, URIs are used instead of strings to avoid the issue of polysemy where one word has multiple meanings. In this situation, one would use two different URIs to refer to the "bank" of a river versus a financial institution.

In the Open Annotation Core model, the tag is represented as the Body of the Annotation, and the resource being tagged is the Target. For example, one might wish to associate the textual tag "paris" with an image of the capital of France to describe what is being depicted. Similarly, "capital", "city", "photo", "stunning" might all be used as tags for the same image. This situation is modeled using the same method as embedded textual bodies described in the previous section. The body resource SHOULD also have the oa:Tag class assigned to it, as applications render comments and tags in very different ways. Figure 2.1.3.1 below depicts this.

For semantic tags, where the tag is expressed as a URI, the Body is the URI of the tagging resource. The above example might instead use the URI http://dbpedia.org/resource/Paris as the Body, and is typically a term from a controlled vocabulary intended to be widely reused. It is also necessary to know that this resource should not be retrieved and rendered for the user, and thus the oa:SemanticTag class MUST be associated with the tagging resource. Note well that semantic tags, and other URIs, may have a fragment component, where the purpose is NOT to select a segment of the document. As such, these resources MUST NOT be re-expressed using FragmentSelectors as that would mean they were selecting a segment of interest. The semantic tagging model is depicted in Figure 2.1.3.2.

As explained in the Motivation section, Annotations that tag resources, either with text or semantic tags, SHOULD also have the oa:tagging motivation to make the reason for the Annotation more clear to applications, and MAY have other motivations as well.

It is NOT RECOMMENDED to use the URI of a document as a Semantic Tag, as it might also be used as a regular Body in other Annotations which would inherit the oa:SemanticTag class assignment. Instead it is more appropriate to create a new URI and link it to the document, as demonstrated in figure 2.1.3.3 using the foaf:page predicate.

Model

Vocabulary Item	Type	Description
oa:Tag	Class	A class assigned to the Body when it is a tag, such as a embedded text string
oa:SemanticTag	Class	[subClass of oa:Tag] A class assigned to the Body when it is a semantic tagging resource; a URI that identifies a concept, rather than an embedded string, frequently a term from a controlled vocabulary
foaf:page	Relationship	The foaf:page relationship expresses the link between a Semantic Tag and the document that describes or somehow embodies the tagging concept.

Figure 2.1.3.1. Textual Tag

  <anno1> a oa:Annotation ;
    oa:motivatedBy oa:tagging ;
    oa:hasBody <tag1> ;
    oa:hasTarget <target1> .
    
  <tag1> a oa:Tag, cnt:ContentAsText ;
    cnt:chars "tag" .
  <target1> a dctypes:Image .

Figure 2.1.3.2. Semantic Tag

  <anno1> a oa:Annotation ;
    oa:motivatedBy oa:tagging ;
    oa:hasBody <term1> ;
    oa:hasTarget <target1> ;

  <term1> a oa:SemanticTag .
  <target1> a dctypes:Image .

Figure 2.1.3.3. Semantic Tag, referring to a Document

  <anno1> a oa:Annotation ;
    oa:motivatedBy oa:tagging ;
    oa:hasBody <term1> ;
    oa:hasTarget <target1> ;

  <term1> a oa:SemanticTag ;
    foaf:page <document1> .

  <target1> a dctypes:Image .

Usage

  SELECT ?anno WHERE { ?anno oa:hasBody ?body . ?body a oa:Tag }
=> <anno1>

Fragment URIs Identifying Body or Target

Many Annotations are about part of a resource, rather than its entirety. Resources can be arbitrarily large, and annotations arbitrarily precise as to their segment of interest. In the Architecture of the World Wide Web, segments of resources are identified using URIs with a Fragment component that at the same time both describes how to extract the segment of interest from the resource, and identifies the extracted content. For simple annotations, it is valuable to be able to use these fragments as either Body or Target.

It is important to be aware of the consequences of using a Fragment URI for the purpose of identifying parts of a resource, and the restrictions that using them places on implementations.

• Most fragments are defined with respect to individual media types, and not every media type has a fragment specification.
• Even if a media type does have a fragment definition, it is often not possible to describe the segment of interest sufficiently precisely. For example, fragments for HTML cannot be used to describe an arbitrary range of text.
• It is not possible to determine with certainty what is being identified without knowing the media type, as the same fragment string might be possible in different specifications. For example, the same fragment string could identify either a rectangular area in an image, or a strangely named section of an HTML document.
• Fragment URIs are not compatible with other methods of describing the segment more specifically, described in the Specific Resources module of this specification. It is recognized that this additional level of description is not required in all scenarios, however.
• As URIs are considered to be opaque strings, annotation systems may not discover annotations with fragment URIs when searching by means of the URI without the fragment. For example, an Annotation with the Target http://example.com/image.jpg#xywh=1,1,1,1 would not be discovered in a simple search for http://example.com/image.jpg, even though it is part of it.

For systems where these issues are not a concern, or would provide a significant burden to implementation, Fragment URIs MAY be used as either the Body or Target of an Annotation. It is otherwise RECOMMENDED to use the Selector mechanism described in the Specific Resources module, which includes a transition mechanism (oa:FragmentSelector) to ensure compatibility with existing and future fragment specifications.

Model

Figure 2.1.4. Fragment URIs

  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <t1#xywh> .

  <body1> a dctypes:Text .
  <t1#xywh> a dctypes:Image .

Usage

  SELECT ?anno WHERE { ?anno oa:hasTarget <t1#xywh> }
=> <anno1>

  SELECT ?anno WHERE { ?anno oa:hasTarget ?x . FILTER ( regex (str(?x), "^t1")) }
=> <anno1>

See Further Examples

Annotations without a Body

A special case exists when the Annotation does not have a Body resource. Examples of this sort of situation include bookmarking a particular resource, marking a point within a resource, and highlighting a section of a resource without making a comment about why it is highlighted. A Body may be added to these Annotations later, perhaps explaining the importance of the resource and thus why it was bookmarked.

No new relationships or classes are introduced for Annotations without a Body.

Model

Figure 2.1.5. Annotations without a Body

 <anno1> a oa:Annotation ;
    oa:hasTarget <target1> .

Usage

 SELECT ?anno
  WHERE { ?anno oa:hasTarget <target1> .
    FILTER(NOT EXISTS { ?anno oa:hasBody ?notbody })
  } 
=> <anno1>

See Further Examples

Multiple Bodies or Targets

Conversely to the previous section, it is also possible for an Annotation to have multiple Bodies and/or Targets. Each Body is considered to be equally related to each Target individually, rather than the complete set of Targets. This construction may be used so long as dropping any of the Bodies or Targets would not invalidate the Annotation's meaning. Thus in Figure 1.1.5 below, all of the following are individually true:

• body1 is about target1
• body1 is about target2
• body2 is about target1
• body2 is about target2

Example use cases include having multiple tags about a single target image, or a single comment that applies to several web pages.

For situations when the Annotation needs different semantics for multiple Bodies or Targets, such as when a comment is comparing or contrasting the Targets, and hence not about each equally and individually, it is necessary to use further constructions described in the Multiplicity module. It also allows the Bodies or Targets to be ordered, or for a choice to be made by the client on which one of the resources is most appropriate for the user.

The Open Annotation model does not define any new relationships to enable multiple Bodies or Targets. The oa:hasBody and oa:hasTarget relationships are used multiple times with the same Annotation as the subject.

Model

Figure 2.1.6. Multiple Bodies or Targets

  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasBody <body2> ;
    oa:hasTarget <target1> ;
    oa:hasTarget <target2> .

Usage

  SELECT ?anno WHERE { ?anno oa:hasTarget ?t1 ; oa:hasTarget ?t2 . 
    FILTER( ?t1 != ?t2 ) }
=> <anno1>

See Further Examples

Agents

This section recommends best practices for recording information about the agents involved in the Annotation, in particular the annotator and serializer.

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 required. The PROV class is used as FOAF does not define a SoftwareAgent class. prov:Agent and foaf:Agent are equivalent classes.

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:annotatedBy relationship
prov:SoftwareAgent	Class	The class for a software agent, typically used as the class of the object of the oa:serializedBy relationship. It might also be used for the object of the oa:annotatedBy for machine generated annotations.
foaf:Organization	Class	The class for an organization, as opposed to an individual. This might be used as the class of the object of the oa:annotatedBy relationship, for example.
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.
foaf:homepage	Relationship	The home page for the agent. Each agent MAY have 1 or more home pages.

Figure 2.2.1 Agent Model

  <anno1> a oa:Annotation ;
    oa:hasBody <body1> ;
    oa:hasTarget <target1> ;
    oa:annotatedBy <agent1> ;
    oa:serializedBy <agent2> .
  
  <agent1> a foaf:Person ;
    foaf:openid <OpenId1> ;
    foaf:name "A. Person" .
    
  <agent2> a prov:SoftwareAgent ;
    foaf:homepage <HomePage1> ;
    foaf:name "Code v2.1" .

Usage

   SELECT ?anno WHERE { ?anno oa:annotatedBy ?who . ?who a foaf:Person }
=> <anno1>

See Further Examples