W3C Workshop: Annotation on the Web

Expression of Interest

Nick Stenning, Open Knowledge Foundation


In 2009, the Open Knowledge Foundation started work on the code that would subsequently become Annotator, the JavaScript library that sits at the core of the Hypothes.is project, the MIT Annotation Studio, as well as recent annotation features added to EdX, one of the largest online course providers in the world.

Over the course of the last five years, Annotator has grown from a single-purpose tool supporting a single project (Open Shakespeare) into the foundations on which a wide variety of annotation tools have been built. Its modular architecture (it is easy to extend Annotator’s behaviour with plugins) has borne a vibrant developer community who have contributed plugins for numerous kinds of annotation applications and media.

I and the other contributors to the project (Annotator is free software and developed in the open, on GitHub) are currently gearing up to release Annotator v2.0.0, which represents a substantial consolidation and improvement of Annotator’s internal architecture. Our aim is to position Annotator squarely at the centre of annotation on the open web, helping developers build annotation-based applications of all shapes and sizes by allowing them to focus on the difficult user experience challenges that they face, while relying on the tested Annotator code for their core functionality.

Point of View

Annotator is the most widely deployed annotation platform on the open web, and tries to provide a generic “platform layer” for the development of annotation-based applications, solving such problems as:

In particular, the architecture of Annotator v2.0.0 will make it possible for third-party developers to assemble annotation-based applications from a wide range of Annotator-ecosystem components published as CommonJS packages on the NPM (“Node Package Manager”) registry.

For the most part, Annotator does not have perfect answers to the challenges listed above, but we do have experience with almost all of them, and in many cases the solutions have been tested in real applications. We would like to share our experiences with some of the most difficult problems, and solicit feedback and suggestions from other workshop participants in order to build better annotation applications.


Annotator, Hypothes.is, and many other web annotation systems have historically been built on systems that rely on the injection of JavaScript code into a 3rd-party webpage. This is a fragile mechanism to use on the open web, where most of the DOM API is mutable, and we have experience with Annotator breaking on websites that modify the DOM and DOM APIs in unexpected ways.

Code that works in this way is about to become even more fragile, thanks to the deployment and adoption of Content-Security-Policy, a technology designed to defend web authors from cross-site scripting attacks. This new HTTP header and associated user-agent enforcement will ensure that code cannot run in a page context if it is from an origin (domain) that is not explicitly authorised by the served page. This is undoubtedly a good thing for the web, but any implementation of annotation across the web will have to address this new restriction.

At the workshop, I would like to introduce this problem and the various solutions or workarounds that exist at the moment, their complexities and deficiencies, and to start a conversation about what we can do better to ensure the continuing viability of open annotation technology on the web.