kbai/anno-common repository overview

⁠anno

Look here for the documentation⁠

This monorepo contains packages that provide the building blocks for annotation software implementing the Web Annotation Data Model⁠ and Web Annotation Protocol⁠.

Each repository is designed to provide a single feature to allow for broad reuse of components.

• Concepts⁠
  • Store⁠
  • Authentication⁠
  • Revisions⁠
  • Comments / Replies / Nesting⁠
  • URL schema⁠
  • Extensions to Web Annotation Data Model⁠
• Hacking⁠

⁠Concepts

⁠Store

A store provides persistent storage of annotations. A store exposes methods that reflect the Web Annotation Protocol⁠ and the extensions implemented of this framework⁠.

The store⁠ module is a proxy⁠ to the actual implementation. It handles method dispatch and middleware and allows instantiation from the environemnt. Actual stores must implement its interface⁠.

The store-mongolike⁠ module implements most of the store interface ⁠ for document databases, such as mongodb⁠ or NeDB⁠.

⁠Authentication

Authentication is based on JSON Web Tokens⁠.

To inspect your tokens, try jwtinspector browser extension⁠ which will detect JWT in HTTP traffic and localStorage.

⁠Revisions

An oa:Annotation has 1..n annox:hasVersion annox:AnnotationRevision.

annox:hasVersion is an ordered List.

The top-level oa:Annotation has the data from the latest revision as

• body
• target
• creator

The modified of the top-level oa:Annotation is the created of the latest revision.

hasVersion is part of the getMetadata⁠ store call/HEAD HTTP call.

⁠Comments / Replies / Nesting

⁠URL schema

ID is a nice slugid⁠, based on uuid v4 without leading dash

<BASE_URL>/<ID>[.<REPLY_ID>]*[~<REVISION_ID>]

E.g.

• http://localhost:3000/ewnfkjewnfew~2 Second revision
• http://localhost:3000/ewnfkjewnfew.2.1~5 Fifth revision of first answer to second answer

Replies reply to the generic not versioned annotation (for sanity)

⁠Extensions to Web Annotation Data Model

Namespace for extensions is https://kba.github.io/anno/#, short annox.

Context is at https://anno.github.io/anno/context.jsonld

⁠Hacking

Modules are managed by lerna⁠

npm install -g lerna
lerna bootstrap