Open Annotation Architecture and Scope

Name: Jake Hartnell

Affiliations: / UC Berkeley School of Information / Epub.js

Working for, I have many things to say about annotations but none more so than: annotations should be based on open standards and part of the browser.

Since many likely agree with that statement, I’d like to use this proposal to breifly outline the following initial thoughts:

  1. Annotations deserve their own element.
  2. The browser should handle selection, attachment, and display of annotation documents in a sidebar interface.
  3. Storage should be handled by external services.
  4. This will strengthen books in the browser


While I don’t intend this to be a technical specification, I would like to see annotations become a web resource that represents the semantic meaning of “marginalia.” Annotations have always had a a spatial relationship to content and documents, and in electronic form they should be able to be embedded in html documents. In other words, while annotations are web resources they should also be able to be a part of documents.

An element or attribute of annotations could also allow a form of transclusion, whereby one can take a selection from another document and have it show up else where (like images currently function). This could result in amazingly powerful citation tools, and is something I feel is badly needed on the web.

Again, the idea of an element is a bit murky and overshadows much of the technical details, but it would open up many possibilities for developers building new types of applications.

Additionally, though this is a minor point, elements and attributes are easier for less techinically minded to wrap their heads around as many people who don’t have a clue about html understand the concept of embedding: copy this text, paste it somewhere else, and it works.


The browser should handle as much as possible reguarding selection, attachment, and the display of annotaton.

Since I feel others may have covered selection and attachment, I would like to focus on display.

Annotation interfaces are hard. Especially if we are dealing with annotations coming from many different services with different specialities and perspectives (note taking, peer review, discussion, etc.). These web resources need a space in which to live and be displayed. Browsers should provide and help the user manage this space.

The sidebar approach is the best approach I’ve seen to dealing with annotation, and at I’ve been working with it since the beginning. Browsers should have a sidebar where annotation documents (perhaps similar to iframes) could be displayed, sorted, searched, and filtered through. While this presents many difficult—though not unsolvable—UX problems (notably switching between channels), it allows for more flexibility in that annotation stores will be able to use different styles of cards and customize the interface of their annotation documents.

Annotation stores (a.k.a. Channels):

I like the idea of channels because like with television, they are things that you have to tune into. Users should be able to add, remove, and filter by channels in the browser, thus giving them power to control what (if anything) they see. could be such a channel, but there will be others. For example, there could be private channels such as a Mooc class for instance, or perhaps a channel by Rap Genius.

There are many highly specific use cases such as copyediting, classroom use, semantic markup, note taking, etc. that could all require different types of annotation cards. This diversity is good, and different channels should be given the tools to experiment with different models. Annotation is a very general activity, and while the acts of selecting, attaching, and displaying can be standardized, what happens afterwards should not be. While browsers might optionally provide local storage for annotation, I don’t think storage is in scope.


Finally, I’ll conclude with a big personal interest of my own. I would like to see the open annotation of ebooks. Currently, I’m contributing to the open source library Epub.js, a JavaScript library for rendering books in the browser. I think there are lots of exciting possibilities for reading and annotating ebooks on the web and I would like to see browsers provide this functionality rather than closed proprietary platforms like Amazon and Apple.