Defining new types

The Annotea [Annotea] annotation, reply, and also bookmark types are defined by using RDF [RDF]. The basic annotation namespace [AnnotationNS] defines an abstract a:Annotation class and similarly the reply namespace [ReplyNS] defines an abstract a:Reply class. In addition, there exists a small set of predefined subtypes for annotations [AnnotationTypeNS] and for replies [ReplyTypeNS].

If the predefined annotation and reply subtypes are not satisfactory, it is possible to define new annotation or reply types or replace the predefined types. This document describes how this is done in Amaya. It also gives an example of how to add alternative icons to annotation types.

Our future plan is to have an easy user interface for adding new types, adding new icons to the types, and defining how to present the types in general.

The classes and properties described in this document use the following conventions for the namespace definitions:

2. Defining a new annotation type in a schema

It is possible for a working group or any other group using Annotea to define it's own set of annotation types. For instance, Figure 2.1 has a definition of a new annotation type e:Kudos [Moore], which can be used to add congratulations as annotations to documents.

<rdf:RDF
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">

<rdf:Description about="http://www.w3.org/2003/07/MyAnnotTypes#">
  <rdfs:comment>A namespace for describing types of annotations</rdfs:comment>
  <rdfs:comment>$Revision: 1.5 $ $Date: 2004/01/15 20:08:03 $</rdfs:comment>
  <rdfs:seeAlso resource="http://www.w3.org/2000/02/Collaboration/Annotation/papers"/>
</rdf:Description>

<rdfs:Class rdf:about="http://www.w3.org/2003/07/MyAnnotTypes#Kudos">
  <rdfs:label xml:lang="en">Kudos</rdfs:label>
  <rdfs:comment>A class of Annotations representing positive congratulations</rdfs:comment>
  <rdfs:subClassOf rdf:resource="http://www.w3.org/2003/07/annotation-ns#Annotation"/>
  <rdfs:isDefinedBy resource="http://www.w3.org/2003/07/MyAnnotTypes#"/>
</rdfs:Class>

</rdf:RDF>

Figure 2.1: Definition of a new annotation type e:Kudos

This new annotation could also have some new properties not defined in annotation namespace [AnnotationNS]. Currently, these properties would need to be created by the client and would need some programming. If they would exists, e.g. because a client knew how to create them, the Annotea server would store and fetch them together with other properties even though it might not be able to present it in the user interface without some programming.

3. Adding a new schema to Amaya

Amaya reads config/annot.schemas file, that is located in Amaya directory, to find out which annotation, reply and bookmark related schemas it needs to read. It usually stores a local copy of the main schemas to ensure no network connection is needed for annotations or bookmarks to work.

Currently, the file needs to be edited outside Amaya to add a new schema definition to it. The file defining the schema with e:Kudos class is added in the last line of Figure 3.1. In this case it is read directly from the Web.

# annot.schemas
#
# specifies the RDF schemas to be pre-loaded for Annotations
#
# each line beginning with '#' is a comment
# all other non-empty lines must be in one of two formats:
# 1. namespacename
# 2. namespacename filename
#
# In case 1, an RDF schema is expected to be found at the namespace URI
# In case 2, the filename is expected to be a (local) copy of an RDF
#            schema for the namespace.  The strings $THOTDIR and
#            $APP_HOME may be used at the beginning of the filename
#            and will be expanded to the Amaya installation directory
#            and the user's amaya home directory respectively.

# Historical schema presented at WWW9. Obsolete.
#http://www.w3.org/1999/xx/annotation-ns#

#first release schema; do not change unless you also change the service
http://www.w3.org/2000/10/annotation-ns#  $THOTDIR/config/annotschema.rdf

#some Annotation subclasses that we think will be useful
# use ANNOT_DEFAULT_TYPE in thot.rc to specify a default
http://www.w3.org/2000/10/annotationType# $THOTDIR/config/annottypes.rdf

#release 5.2 threading
http://www.w3.org/2001/03/thread# $THOTDIR/config/thread.rdf
# use REPLY_DEFAULT_TYPE in thot.rc to specify a default
http://www.w3.org/2001/12/replyType# $THOTDIR/config/replytypes.rdf

#user-defined icons
http://www.w3.org/2001/10/typeIcon# $THOTDIR/config/typeIcon.rdf

#to add new types
http://www.w3.org/2003/07/MyAnnotTypes#

Figure 3.1: Telling Amaya to read the new annotation types from the Web

Although not currently implemented in Amaya, a client could define a user interface for adding the schema files from the Web and possibly also copying them to local Amaya config directory. Next step would be to make it easy to share these definitions within a group of users.

4. Defining a new icon for a type

In Amaya releases after 6.2 the icon used to mark the location of an annotation within an annotated document may be changed by the user. In release 6.2 the icon that denotes an annotation is chosen as a property of the annotation type.

The icons are defined by including a i:usesIcon property for each annotation type you wish to define a separate icon. Figure 4.1 shows an example of that.

<rdf:RDF
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:i = "http://www.w3.org/2001/10/typeIcon#">

<rdf:Description rdf:about="http://www.w3.org/2000/10/annotationType#Question">
  <i:usesIcon rdf:resource="file:///home/question-icon.jpg" />
</rdf:Description>

</rdf:RDF>

Figure 4.1: Adding an icon to an annotation class

The file containing the icon definitions needs to be added to config/annot.schemas file in the same way as the file defining the new annotation types is added in section 3. The definition in Figure 4.1 is part of the http://www.w3.org/2001/10/typeIcon# definitions, so it is already part of Amaya unless it is commented away.

Amaya supports JPEG, PNG, and GIF bitmap graphics formats for icon images. Currently, the icon URI may only be a file: URI; that is, the icon must appear in a local or mounted directory to Amaya. Two special forms of non-file: URIs are supported. If the file path name starts with "$THOTDIR" or "$APP_HOME" then the corresponding Amaya installation directory or personal Amaya home directory is substituted into the pathname.

We are looking for possibilities to make the icon definitions more dynamic and have a better user interface for making these definitions.

Defining new annotation types with Amaya

1. Introduction

2. Defining a new annotation type in a schema

3. Adding a new schema to Amaya

4. Defining a new icon for a type

References