Overview
Apache Annotator provides software modules to facilitate annotation tools in web browser environments. For example, it could be used in web-based document viewers or browser extensions that let users highlight phrases and place virtual sticky notes on the pages they visit.
The modules are written in TypeScript, and distributed as Javascript/ECMAScript modules on NPM. Read further for a high-level description of the code functionality, or get started with it directly!
What is in the box
Selector tools
The main functionality Apache Annotator offers is to map a Web Annotation Selector to the segment of a document it corresponds to, sometimes called ‘anchoring’ a Selector; and, vice versa, to create a Selector that describes a given selection in the document precisely and unambiguously, such that other Web Annotation software knows exactly where it points to. The purpose of Selectors is to point at any part of a document without requiring any modification of the document itself.
The W3C Web Annotation Data Model outlines a number of different selectors types, to accomodate various use case on different types of documents and selections (e.g. an annotation may target a phrase of text, or a region within an image). The table below shows the full list of defined types and the implementation status of each.
| Selector | Description | Implemented? |
|---|---|---|
| Fragment | Uses the fragment part of an IRI defined by the representation’s media type. | No |
| CSS | CSS Selectors allow for a wide variety of well supported ways to describe the path to an element in a web page. | Yes (for DOM) |
| XPath | Implements an XPath based selection. | No |
| Text Quote | This Selector describes a range of text, including some of the text immediately before (a prefix) and after (a suffix) it to distinguish between multiple copies of the same sequence of characters. | Yes (for DOM and on any text) |
| Text Position | This Selector describes a range of text by recording the start and end positions of the selection in the stream. | Yes (for DOM and on any text) |
| Data Position | 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. | No |
| SVG | An SvgSelector defines an area through the use of the Scalable Vector Graphics standard. | No |
| Range | A Range Selector can be used to identify the beginning and the end of the selection by using other Selectors. | Yes (for DOM) |
| Refinement | Select a part of a selection, rather than as a selection of the complete resource. | Yes |
Web Annotation JSON validator
The source code also includes a script for validating Web Annotation Data Model JSON documents against the data model schema. Having installed from source, one can run:
$ yarn validate --url https://raw.githubusercontent.com/w3c/web-annotation-tests/master/tools/samples/correct/anno1.jsonWith the --url option you can pass in a URL or a local path to a JSON file.
See some example JSON files from the W3C. Note that this validator only tests the data model is followed, and not e.g. whether its target actually exists.
What Apache Annotator is not
Apache Annotator is not an all-in-one annotation tool; rather, it helps others create annotation tools. It does not have opinions regarding in which database on which computer annotations are stored, nor how they are made, exchanged or displayed. Those questions are considered application-specific and left to the developer. Our goal is that the developer can focus on exactly those questions, and forget about issues that are common among annotation tools: finding the part in the document that is being annotated, dealing with changes in the annotated document, ensuring compatibility with other tools, and so on.