A SANE approach to annotation in the digital edition


Robinson and others have recently called for dynamic and collaborative digital scholarly editions. Annotation is a key component for editions that are not merely passive, read-only repositories of knowledge. Annotation facilities (both annotation creation and display), however, require complex software, and if only for that reason it makes sense to share these facilities among edition sites. The paper argues we therefore need a protocol for requesting (and serving) annotations, and a markup vocabulary for storing annotations. The paper proposes a SANE (Scholarly ANnotation Exchange) Request Protocol (SANE-RP) and a SANE Markup Language (SANE-ML) and shows an experimental implementation of these in annotations to a digitised emblem book. The edition (the process that generates the edition HTML from the edition XML source) requests annotation information from an annotation server using SANE-RP. The annotation server serves out the annotations (created using the annotation tool EDITOR) stored in SANE-ML.


1. Introduction


Recent [1] discussion about the scholarly digital edition has focussed on ways to change the edition from a passive text, only there to be consulted, into a dynamic research environment. Siemens asks why as yet we have seen no convincing integration between text analysis tools and the hypertext edition. [2] An essential step towards seamless integration of text analysis tools into the digital edition (TAML, the Text Analysis Mark-up Language) has been suggested [3].


The most visionary statement of the dynamic edition’s potential is no doubt given by Robinson. [4] A dynamic edition, in his view, while offering text analysis and other tools that may shed light on some aspect or another of the edited texts, would also be open to the addition of new content, of corrections, and of many different types of annotations.


This article will focus on making available third-party annotations in the digital edition. A digital edition, in our perspective, consists of (1) an XML source file (or a collection of XML source files), probably encoded according to the Guidelines of the Text Encoding Initiative [1], (2) a set of HTML pages, image files and/or other output formats, used to display the edition contents to the online reader, and (3) a transformation process or other application that produces (2) from (1). The main challenge in annotation of a digital edition (and that which makes the task different from web annotation in general) is that the annotations should refer to the XML source file, but should be displayed to the reader in the context of the output files.


The article continues our work on the EDITOR annotation tool [5]. EDITOR facilitates creating annotations to XML files. The annotations can have user-defined types, they consist of multiple fields, and those fields can have their own data type. The annotations are created in sets, that are expected to have some internal coherence (perhaps studying a single subject, perhaps made to support the argument of a single article). They are not stored within the edition XML but in a separate file on disk. EDITOR also includes a facility (very limited at present) for display of these annotations over the web. In this article I will describe work on a prototype for a component that will facilitate the inclusion of EDITOR-created annotations in the digital edition. The article will propose exchange standards for requesting annotation information from annotation servers, and these standards will create the possibility for connecting other annotation creation tools and annotation display tools.


We will begin by discussing related work, in section 2. The remainder of this article will introduce a markup language and a request protocol for the exchange of annotation information (in section 3); section 4 will discuss a prototype built using this protocol and markup language. In section 5 we will examine some issues arising from the approach. Conclusions and future work will be outlined in section 6.


2. Related work


Annotation technology is a wide field, that is not easy to map. Most of the work in annotation studies, however, seems to centre on web annotation, annotation in digital libraries or annotation as a collaboration tool. While these terrains have much in common with annotating the digital edition, there are also important differences.


As said before, the essential difference between web annotation and annotation of the digital edition is that the object of annotation in our case is not a (series of locations in a) web page. It is a location in an XML source file that is nontrivially transformed into one or more web pages. The annotated file itself is not visible to the reader. In the case of edition annotation, therefore, the edition server must insert the annotations into generated HTML pages based on its knowledge of the transformations applied to the XML source file. This makes all but impossible what is quite common for web annotation, that the annotated pages are typically not ›aware‹ of having been annotated. That is why web annotation systems, such as W3C’s Annotea project [6], can have annotation clients (such as Annozilla, [2]) that insert the annotation information into the HTML pages that the user sees. While that approach makes for simplicity with regards to the annotated objects, it also necessarily limits the amount of integration that can be achieved between the annotation display and the annotated HTML pages. In our case, the edition server must be aware of the existence of annotations, and it must take responsibility for showing these to the user. While this may be an extra complication, it also makes possible an integrated display of content and annotations that is essential for facilitating in-depth study of either. [7]


A number of studies have reported on digital library annotation systems. In the annotation typology developed by Marshall these systems seem mostly to focus on (hyper-)extensive annotation. [8] Scholars use the system described by Agnosti to annotate relations between images in digital manuscripts. [9] Arko et alii describe a system where patrons can annotate resources in a digital library as to their usefulness. [10] For us, one of the interesting things about their approach is that they describe a procedure for annotation exchange using the Open Archive Initiative’s Protocol for Metadata Harvesting (OAI-PMH, [3]). Our proposal for an annotation exchange protocol was in some respects inspired by the OAI-PMH. The OAI-PMH protocol itself is not suitable for the kind of exchange we envision here, for a number of reasons:


the requested information in our case will not always be plain (meta-) data, but may also be counts of items (annotations) or annotation information already formatted for display;


OAI-PMH requests are typically made to get all of the data in a repository and store them for later use; the requests we envisage are made to serve a specific user request and therefore must support fine-grained ›selective harvesting‹: getting annotations selected by for instance annotation type and/or annotation value and/or annotated location (»give me all annotations of type pronoun, where number is singular, that apply to the last stanza of poem x«).


Annotation as a tool for collaboration is in itself a very wide field. Its application ranges from the creation of business documents in a workgroup [11] to scholarly cooperation [12]. Most initiatives seem to assume however that there is a single context for annotation creation and annotation display, that is shared between the collaborating persons. In many cases, this will be a reasonable assumption. In the case of digital edition annotation, however, the creation and display contexts are crucially different. In the present article we will also focus on exchange of annotations between multiple tools or repositories.


3. Introducing SANE


Design considerations


The protocols and software for annotation exchange that we discuss here will be collectively called SANE, short for Scholarly ANnotation Exchange. In designing SANE, we were guided by the following considerations:


• While some annotations may be stored within edition source files, these are not the annotations that are our present concern. The editors that create an edition will want to include the annotations they regard as necessary. SANE focuses on providing annotations from third parties, and even if it would be feasible to include all third-party annotations in the edition source file, that file should not be exposed to the risk of corruption that comes with any kind of change. The annotations that we are concerned with are therefore stored outside of the edition source files.


• Annotations refer to stable locations in edition source files. We assume that if the edition should change, the older version, including its source, will remain available.


• We assume a model where the annotation handling is relegated as much as possible to a specialized annotation server. This server may, but need not, run on the same physical machine as the edition application. There are multiple reasons why this model makes sense: (1) annotation processing may be a heavy task, requiring the presence of infrastructural software (for instance databases, indexing software) that the edition machine not necessarily houses and the edition systems staff is not necessarily comfortable with; (2) annotations may have a complex internal structure that the edition should not have to be aware of (EDITOR-created annotations for instance have that complexity); and (3) annotation display functionality may be complex.


• While leaving the annotation handling to the annotation server wherever possible, in the context of the digital edition it is still the edition server that is ultimately responsible for the annotation display. To decide where and how to display the annotations requires knowledge of the structure and semantics of the edition source XML and knowledge of the logical structure of the edition’s user interface.


• Apart from a protocol for annotation exchange, we also need agreement on a storage format. We will not just want to display a selection of annotations in a specific context (which is what the request protocol will allow us to do), we will also want to do wholesale import or export into or from multiple annotation tools. Because of this, we will introduce both a markup vocabulary and an exchange protocol for annotation information. See below for a further discussion of the question why we need both of these.


The next two subsections will introduce the SANE Markup Language and Request Protocol that facilitate the communication between annotation creation tools, annotation servers and edition servers. In the last subsection of this section we will look at other possible usage scenarios.


SANE Markup Language


The SANE Markup Language, or SANE-ML for short, is an XML markup vocabulary that can be used to store or exchange annotation information. It is defined by a Relax NG schema. A SANE-ML document describes a single annotation set. The data model at present reflects the EDITOR data model [13], but it is intended to be tool-independent. An initial, annotated version of the schema is available online [4].


A SANE-ML document contains multiple sections. Their contents are briefly described in Table 1. Please refer to the schema annotations for more detail.


Table 1 Sane-ML sections



Contains information at set level: name, author, creation and modification dates, rights information, program and program version used to create the annotation set, contact information, (references to) extended prose description of the purpose and meaning of the annotations.


Contains information about the edition(s) annotated in the current set: URL, checksum and a brief description.


Contains information about the scholar-defined annotation types: name, description, and, most important, the fields of which they consist. The fields in their turn have a name and description. Besides that, fields have a data type, and they may have a number of default values.


Contains information about the annotations themselves: the editions and the locations in the editions that they refer to, the annotation type that they instantiate, the text selected for the annotation and the annotation’s values for each of the annotation type’s fields.


Besides (meta-)data about the annotations, a SANE-ML document may also contain information about appropriate display characteristics for the annotations. At the set level, a default colour scheme can be defined. A property at the annotation type level specifies whether highlighting the selected text in the edition is appropriate for this annotation type (for annotation types that are typically applied at the word or phrase level this property will probably be set to true; annotation types that apply to larger text units, such as chapters, will have the property set to false).


SANE Request Protocol


The SANE Request Protocol, or SANE-RP, defines a protocol for the exchange of annotation information between an annotation server and an annotation requestor. As in the Open Archive Initiative’s OAI-PMH protocol, requests consist of a verb with a number of parameters in the URL querystring.


The SANE-RP mode-parameter is used to request either output as XML data, to be processed by the requesting application (mode=data), or as XHTML and/or SVG data, ready to be displayed to the user (mode=display). With mode=display, only minimal effort is required from the application for displaying the annotation information.


Presently defined SANE-RP verbs are:


Table 2 Sane-RP Verbs



Description: requests identifying information from the annotation server, such as name, SANE-RP protocol level that it understands, default rights information, contact information, etc.

Required parameters: mode.


Description: requests set level information, including information about the annotated editions and some information about the available annotation types.

Required parameters: mode, setName.


Description: requests annotation type information, including the description of the annotation fields that the type contains.

Required parameters: mode, setName, typeName.


Description: requests the number of annotations of a certain type, and distributions of values for its constituent fields (of type category).

Required parameters: mode, setName, typeName.


Description: requests the number of annotations of a certain type, by textual unit. The textual units are defined by a parameter (nodeListURL) that refers to a file that lists the top nodes that define the units.

Required parameters: mode, setName, typeName, nodeListURL.

mode=display will return an SVG bar chart of the annotation count by textual unit.


Description: requests data about a single annotation.

Required parameters: mode, setName, annotationId.


Description: requests data about annotations to a single node and its descendants (editionNode parameter) or to a series of nodes (nodeListURL parameter). Returns node elements with the applicable annotations. Optionally filters the annotations by annotation type, field, and/or value.

Required parameters: mode, setName, editionNode or nodeListURL.

Optional parameters: typeName, typeFieldName, searchTerm.


Description: from a list of nodes (nodeListURL parameter), getAnnotationNodes returns the subset of those nodes of which a descendant has been annotated. Optionally filters the annotations by annotation type, field, and/or value.

Required parameters: mode, setName, nodeListURL.

Optional parameters: typeName, typeFieldName, searchTerm.


Description: requests XML edition fragments with included annotation markers, either for a single node (editionNode parameter) or for a series of nodes (nodeListURL parameter). The annotation markers signal the span of text that the annotation applies to. Attributes give annotation id and the annotation type. Optionally filters the annotations by annotation type, field, and/or value.

Required parameters: mode, setName, editionNode or nodeListURL.

Optional parameters: typeName, typeFieldName, searchTerm.


Description: For a category-type field in an annotation type, returns the values of that field and their number of occurrences. With mode=display, the result is formatted as a pie chart.

Required parameters: mode, setName, typeName, typeFieldName.


Description: request suggested display information for an annotation set.

Required parameters: mode, setName.


Usage scenarios


The principal usage scenario for which SANE is being designed is the display of EDITOR annotations in the digital edition. It is easy, however, to imagine other applications for SANE (see Figure 1):


1. Displaying annotations from other annotation tools in the digital edition: annotations created using tools such as Pliny , Atlas.ti [11] or APE could be made accessible from a digital edition if either (1) they can be exported into SANE-ML or (2) these tools provide SANE-RP-based access to their data;


2. Displaying automatically generated information in the edition: the information displayed need not result from manual annotation. The information to be displayed might be the output from a concordance tool, it might be a page popularity count or a list of frequent referrers;


3. Statistical analysis of annotations: the requesting application is not necessarily a digital edition. It might be a piece of software that can be used for statistical analysis of the annotations (perhaps for computing correlations or doing regression analysis);


4. Text mining of annotations: the requesting application might also be a system like nora . Based on the categorisations provided by an annotator it might try to predict a categorisation for other texts in the corpus.


5. Archiving an EDITOR annotation set: researchers may want to safeguard their annotations against eventual disappearance of the EDITOR annotation tool. One possible way to do that is to create a single XML file that contains both the edition source and the annotations that the researcher created. An archiving application could use the SANE-RP getAnnotationFragments verb to request the edition XML enhanced with annotation markers and the getAnnotation verb to request the annotations themselves;


Figure 1 SANE-ML and SANE-RP


In most of these potential applications, there is a use for both SANE-RP and for SANE-ML. From the point of view of the requesting application, what matters is the protocol. The requesting application (the digital edition, the archival tool, the nora-like text mining application) is not concerned with the annotation storage format (SANE-ML). However, from the point of view of the application that creates the annotations or annotation-like information (for instance the page visit counts), the availability of SANE-ML is essential. If there were no SANE Markup Language, these tools would have to write an annotation server of their own. For annotations that are stored in a standard format, an annotation server that knows that standard will know how to handle requests for these annotations.


4. Prototype


In order to test the feasibility of the SANE approach, a prototype has been developed. It consists of an edition of the emblem book Amoris divini emblemata, as digitised in the Emblem Project Utrecht [5], and an annotation server that implements SANE-RP. Both are built in Cocoon [6], the Apache Foundation’s XML publication framework.


The main annotation set used for testing was an annotation set developed to study some aspects of theatricality in the emblem book. Most annotations in this set are made at the level of the emblem (a TEI text-element), others at the level of individual words. Most of the annotation types contain a number of categorisation fields.


To prepare the files for showing them through the prototype, a number of actions were taken:


• The XML edition had been simplified for the purpose of testing EDITOR. Some of the simplifications were removed, and the EDITOR annotation set was changed correspondingly (to keep references correct). This should not ordinarily be necessary. Both actions were done using an XSLT stylesheet.


• The EDITOR annotation set was transformed into a file that conforms to the SANE-ML schema. This involved a change from RDF/XML (which EDITOR uses) into ›plain‹ XML. During the transformation some information was added that EDITOR at present does not store. The transformation was effected using an XSLT stylesheet. I expect future EDITOR versions will use SANE-ML as an export format, making this step redundant.


• To aid performance, a copy of the edition XML source was created where the annotated fragments are marked by seg elements. Overlap between annotations and between annotations and structural elements was handled by, where necessary, creating multiple seg elements for a single annotation. The file was created using two PHP scripts.
A future annotation server would probably include a front-end interface for entering new annotation sets into the annotation repository. One of the tasks to be triggered upon receiving a new annotation set would be the creation of this edition-plus-annotation XML. Alternatively, a production version of the annotation server could use a DOM-structured database for storing the edition XML and the annotations, as suggested by Bradley .


The edition of the emblem book uses the left-hand side of the screen. The edition is very basic and consists of a table of contents and text pages. In a fuller edition, the right-hand side of the screen would be used for translations, commentary, introduction, et cetera. Here, however, we are interested in showing external annotations. In overview, they may be presented as in Figure 2. The options for limiting the display to reviewed annotation sets and for sorting the display are at present inactive. Clicking the server name will fire a SANE-RP identify request, the result of which will be shown below the display options. The identify request, as most of the other requests we will encounter, uses the mode=display option. The results therefore can be included ›as is‹ in the HTML page that the edition creates.



Figure 2 Showing available annotation sets


Selection of an annotation set for display sends a SANE-RP getSetData verb to the annotation server. The results include set level, edition level and annotation type level data, as shown in Figure 3. From here, we have a number of options. Pressing the copyright sign will show us the copyright information for both the edition and the annotation set. We can ask for the annotations to be displayed right away, using the ›add to layout‹ icon on the set or on the annotation type level. On the type level, we can ask for more information about the type (clicking the type name), ask for counts (using the calculator icon), or ask for a bar graph of the number of annotations by textual unit.



Figure 3 Showing an annotation set


Choosing the latter option on the Pronoun annotation type sends a getTypeCountUnit request to the server. If mode=display, the server will answer with an SVG chart of Pronoun annotations by textual unit, as seen in Figure 4. The bar numbers in the chart are hyperlinked to displays of the corresponding emblems with the Pronoun annotations being shown.



Figure 4 Showing the number of annotations
of a certain type by text unit.


Rather than asking for the bar chart, we might also have asked for more information about the annotation type (which would have caused a getTypeData request to be sent to the server). That would result in a display including the annotation type fields. For fields that are categories we could have asked for distribution information (getAnnotationCatCounts verb), which would result in the display of a pie chart of the field’s values. The pie slices again would be hyperlinked to a display of the book with the corresponding annotations being shown (Figure 5).



Figure 5 Showing the distribution of values of a category field


To display the book with (a selection of) the annotations, the edition sends a number of requests to the annotation server. A getAnnotationNodes request returns the nodes that have (descendants that have) annotations that conform to the annotation filter. The resulting list of nodes is used to create a filtered table of contents, which is shown on the left-hand side of the window. A getAnnotationData request returns the annotations themselves, which will be shown at the right hand side. Here the system also displays the active annotation filter. See Figure 6.



Figure 6 Showing a table of contents,
the annotations and the annotation filter.


From here, we have multiple possibilities. Clicking an item in the table of contents, we can ask for an annotated display of an individual emblem. We can also remove one or more of the filter criteria, thus including a larger number of annotations in the display. Depending on the strictness of the filter applied, the annotation display itself might include hyperlinks that add extra selections to the filter.


In Figure 7, we see a display of one emblem from Amoris Divini Emblemata with all available annotations. The XML underlying this display was delivered by the annotation server after a getAnnotationFragment request. In the display, the start and end locations of annotations are marked using coloured triangles. One of the annotations is being shown in full, an action that results from placing the mouse over the opening triangle (which fires a getAnnotation request). Placing the mouse over the closing triangle of an annotation underlines the annotated fragment. This is useful in the case of overlapping, nested or coinciding annotations. We notice some of the annotations have their annotated text highlighted, others don’t. We notice too that each annotation type has its identifying colour. These aspects of the display result from data returned from a getDisplayData verb.



Figure 7 Showing all annotations for an emblem.


5. Discussion


What the prototype does show is that it is feasible to integrate the display of external annotations in the digital edition. It also suggests, I believe, that this integration will prove to be a useful thing. A number of features are still conspicuously missing in this prototype. I intend to add these in a later version. To name a few:


• it should be possible to change the order of displayed annotations;


• it should be possible to have the highlight colour reflect the values of one or more annotation fields;


• it should be possible to display annotations from multiple annotation sets;


• it should be possible to integrate (a simple visualisation of) annotation counts in the edition table of contents;


• it should be possible to search the edition and the annotations conjointly.


The main problem in the creation of the prototype has been the demarcation of functionality between annotation server and edition. A fundamental decision in SANE-RP design was to have the annotation server do as much of the annotation handling as possible. Unlike the OAI-PMH, SANE-RP can be used to create HTML fragments ready for display, using the mode parameter. The advantage of this approach is that the display functionality does not need to be built into the editions that request the annotations. However, as the display of the annotations is meant to be integrated with the edition display, responsibility for display can never lie with the annotation server alone. This creates a situation where the spheres of concern of the annotation server and the edition are not always clearly demarcated. [14] Especially tricky are the hyperlinks included in the annotation display, as they are created by the annotation server but need to be acted on by the edition. [15]


A perennial issue in XML annotation is the fact that annotations do not necessarily fit in the document hierarchy. In our case, we assume the annotations are stored externally, and refer to the annotated fragments using pointers to their begin and end points. They can therefore overlap, nest or coincide both among themselves and with(in) the elements of the XML hierarchy. For display purposes, an hierarchy that aggregates the document and its annotations is built behind the screens, but that is a temporary document, not meant to be seen by the human eye.


6. Conclusions and future work


I opened this article by mentioning Peter Robinson’s vision for the future of the digital edition. The ability to include externally created annotations is only a small step in the realisation of that vision. What I propose here is in some ways even conservative. SANE is about annotation of an existing and stable edition. Within SANE, there is no way for a scholar to add new texts, to correct decisions made by the editor, or to annotate another person’s annotation.


What is then that SANE can mean then for the edition, ›our mutual enterprise‹, as Robinson terms it?


A facility like SANE (in conjunction with an annotation creation tool like EDITOR) will probably be used in one of two ways:


• to add a body of annotations to an edition as a service to the reader, in order to facilitate comprehension of the text and its contexts (annotations to personal names, to obscure places, references to parallel texts elsewhere, to illustrations, etc.);


• to add a body of annotations that support an interpretive or theoretical claim about the edited work. Here the annotations may serve as a linking pin between the online edition and a piece of scholarship, perhaps an article, that they provide the details for.


Both of these applications show the collaborative nature of scholarly work. In the first case, the edition originally created by an editor is enhanced by another scholar for the benefit of a third person, the reader. In the second case the scholar is no longer merely using the edition to create his or her own scholarship (the article), but in return makes the details of that scholarship accessible to the user of the digital edition, and thus to other scholars.


Whether facilities like these will prove to be a success is hard to predict. What seems clear is that the SANE proposal creates an opportunity for new tools that create annotations and new tools that know how to do interesting things with them. The next steps to be taken in order to make annotation exchange along these lines a true possibility are:


• create a formal description for SANE-RP: even though it may be impossible to create a definitive formal description at this stage, people that want to use the protocol need a document to base their implementation upon;


• (perhaps) create a TEI version of SANE-ML;


• create an experimental server that serves the SANE request protocol based on annotation sets that use the SANE Markup Language. This would entail both creating the software and run it as a service for those willing to experiment with SANE client software;


• change EDITOR to use SANE-ML as an export format;


• create a demo edition that shows the benefits of being able to create annotations to a scholarly text, and having these annotations show up in the context of the annotated text.


Taken together, these steps create the conditions for joint experiments in annotation exchange. The editions that we create will profit from being able to include annotations from many different sources.




EDITOR development was funded by the Royal Netherlands Academy of Arts and Sciences [7]. EDITOR was designed by a number of Huygens Institute colleagues (Herman Brinkman, Hanneke van Kempen, Boukje Thijs and myself) and built by a team of programmers, most notably Rutger Kramer and Marc Evers.


The SANE prototype relies on Cocoon and the software components it includes or uses. The SVG graphs were created using a somewhat modified version of ChartSVG [8].

This article is based on a paper presented at Digital Humanities 2006.
Siemens 2005.
Sinclair 2005.
Robinson 2003.
Boot 2005; Boot forthcoming.
Kahan et alii 2001; Koivunen 2005.
The limitations of Annotea’s annotation model are another reason why it is not really suitable for the task of scholarly annotation.
Marshall 1998.
Agosti et alii 2005.
Arko et alii 2006.
Cadiz /Gupta / Grudin 2000.
Van Zundert /Van Dalen-Oskam 2005.
Boot 2005.
As stated above, the edition and the annotation server were built using Cocoon. I am not a Cocoon expert, and I am sure that for most of the things I grappled with there will be more elegant solutions than the ones I came up with. The fact that the issues mentioned in this section arose at all, however, is I believe due to the problems of demarcation between edition and server.
More details about these issues and those discussed in the next paragraph in my forthcoming thesis.