(2021-09-03) Udell Notes For An Annotation Sdk

Jon Udell: Notes for an annotation SDK. While helping Hypothesis find its way to ed-tech it was my great privilege to explore ways of adapting annotation to other domains including bioscience, journalism, and scholarly publishing. Working across these domains showed me that annotation isn’t just an app you do or don’t adopt. It’s also a service you’d like to be available in every document workflow that connects people to selections in documents.

In my talk Weaving the Annotated Web I showcased four such services. ((2017-05-05) Udell Weaving The Annotated Web)

As I worked through these and other scenarios, I accreted a set of tools for enabling any annotation-aware interaction in any document-oriented workflow. I’ve wanted to package these as a coherent software development kit, that hasn’t happened yet, but here are some of the ingredients that belong in such an SDK.

Creating an annotation from a selection in a document

The Hypothesis client formerly used an NPM module, dom-anchor-text-quote, to derive that info from a selection. It no longer uses that module, and the equivalent code that it does use isn’t separately available. But annotations created using TextQuoteSelectors formed by dom-anchor-text-quote interoperate with those created using the Hypothesis client

You’ll find something like TextQuoteSelector in any annotation system. It’s formally defined by the W3C

There are, however, cases where TextQuoteSelector won’t suffice. Consider a document that repeats the same passage three times.

Another selector, TextPositionSelector (https://www.npmjs.com/package/dom-anchor-text-position), enables a system to know which passage contains the selection.

The positions recorded by a TextQuoteSelector can change for a couple of reasons

If the document is altered

Less obviously that can happen even if the document’s text isn’t altered. A news website, for example, may inject different kinds of advertising-related text

So while TextPositionSelector can resolve ambiguity, and provide hints to an annotation system about where to look for matches, the foundation is ultimately TextQuoteSelector.

Building on these ingredients, HelloWorldAnnotated illustrates a common pattern.
Given a selection in a page, form the selectors needed to post an annotation that targets the selection.
Lead a user through an interaction that influences the content of that annotation.
Post the annotation.

user rates the emotional affect of a selection

Although the annotation is created by a standalone app, the Hypothesis client can anchor it, display it, and even edit it.

There’s powerful synergy at work here. If your annotation scenario requires controlled tags, or a prescribed workflow, you might want to adapt the Hypothesis client to do those things. But it can be easier to create a standalone app that does exactly what you need, while producing annotations that interoperate with the Hypothesis system.

Anchoring an annotation to its place in a document

use Hypothesis to describe where notes should anchor, as well as what they should say

An annotation-powered survey

The Credibility Coalition is “a research community that fosters collaborative approaches to understanding the veracity, quality and credibility of online information.” We worked with them on a project to test a set of signals that bear on the credibility of news stories.

create a survey tool that enabled respondents to answer such questions by highlighting one or more selections

A JavaScript wrapper for the Hypothesis API

A Python wrapper for the Hypothesis API

Notifications

h_notify is a tool that uses the Hypothesis API to watch for annotations on individual or wildcard URLs, or from particular users, or in a specified group, or with a specified tag

it can send alerts to a Slack channel, or to an email address, or add items to an RSS feed.

A tiny Hypothesis server

you can follow the instructions here to build and run your own server, and some people and organizations do that. Depending on need, though, that can entail more effort, and more moving parts, than may be warranted.

The documents you’re annotating are public, but the notes you’re taking in a Hypothesis private group are so sensitive that you’d rather not keep them in the Hypothesis service. You’d ideally like to spin up a minimal server for that purpose: small, simple, and easy to manage within your own infrastructure

A tiny app wrapped around those ingredients is all you need to receive JSON payloads from a Hypothesis client

Here’s a proof of concept. This tiny server clocks in just 145 lines of Python with very few dependencies. It uses Python’s batteries-include SQLite module for annotation storage. The web framework is Pyramid only because that’s what I’m familiar with, but could as easily be Flask

Then I made the handful of small tweaks to the Hypothesis client shown in client-patches.txt

This is the easiest way to create a Hypothesis client in which to try quick experiments

In this case I only made the changes shown in client-patches.txt:

I don’t recommend this cowboy approach for anything real

it’s feasible — without forking Hypothesis — to maintain branches that maintain small but strategic changes like this one

Others will see it only if they’re running the same tweaked extension and pointing to the same server.

Signposts

Why decouple? Reasons are as diverse as the document workflows we engage in.