dokieli Web Annotation

W3C Web Annotation implementation for creating, parsing, and serializing Web Annotations in JSON-LD, with support for HTML+RDFa embedding and DOM-based annotation application.

• Code of Conduct
• Contributing Guide
• API Reference
• Security Policy

License

• Source code is licensed under the Apache License, Version 2.0.
• Unless otherwise noted, images and other media assets are licensed under the Creative Commons Attribution 4.0 International.

Installation

npm install @dokieli/web-annotation

or

yarn install @dokieli/web-annotation

import { createAnnotation, serializeAnnotationToJSONLD, serializeAnnotationToHTML } from '@dokieli/web-annotation';

const annotation = createAnnotation({
  motivatedBy: 'oa:commenting',
  body: { value: 'A note.' },
  target: { source: 'https://example.org/', selector: { type: 'TextQuoteSelector', exact: 'annotated text' } }
});

const jsonld = serializeAnnotationToJSONLD(annotation);
const html = serializeAnnotationToHTML(annotation);

Documentation

See API Reference and Examples.

Features

• Parsing and serializing annotations in JSON-LD and HTML+RDFa.
• Support for selectors and states.
• Restoring the selection object from a stored selector.
• Marking the annotated text (the target) in the DOM.

Specifications

• W3C Web Annotation Model
• W3C Web Annotation Vocabulary
• W3C Selectors and States
• W3C Embedding Web Annotations in HTML

Conformance

The data in JSON-LD this library emits conforms to the W3C Web Annotation Data Model, validated against the official w3c/web-annotation-tests suite (its MUST assertions). Run the checks with yarn test:conformance.

Contributing

See the Contributing Guide for development setup, tests, and commit conventions.

Supported By

• This project was funded by NLnet (2025-09–2026-06) as part of NLnet Dokieli Collaborative.

Support the project

Help the project grow by sponsoring it on Open Collective or reach out to us.