Annotation System Requirements

Here are requirements for a W3C specification annotation interface.

The general use case for this annotation interface is issue tracking for the specifications produced by the Web Annotation Working Group, and hopefully would be adopted by other working groups. As such, the product must provide sufficient value-add over existing issue tracking mechanisms in use by working groups to make the barrier to entry worth the learning curve and change of behavior. Using our own specifications is important, but not at the expense of otherwise unnecessary delays and user frustration.

• (1): Priority 1. These items are required for the minimum viable product.
• (2): Priority 2. These items are required for phase 2 or 3 (e.g. 4–8 months).
• (3): Priority 3. These items are nice-to-have, but not required.
• (?): These items are not yet sorted into priorities.

• Annotation client will
  • transfer annotations to a server in a serialization of the W3C Open Annotation Community Group's [OA] data model
  • retrieve annotations without requiring authentication (W3C requirement for not tracking viewers)
  • render annotations from a serialization of the OA data model
  • must not require installation of software (e.g. must run in browsers via script library) (1)
  • work in all common browsers (Safari, Firefox, Chrome, IE) (1)
    • Note: limitations in IE make robust anchoring impossible for now, but non-changed documents will still anchor
  • be able to publish to multiple annotation stores given user configuration (2,3)
    • Priority will depend upon availability of other 3rd-party OA-conforming repos
  • support reasonably robust selection of textual targets in face of changes
  • allow authenticated users to modify and delete existing annotations
  • Annotations on images and parts of images (2,3)
  • Allows multiple targets (2,3)
    • Allows multiple targets in different pages (3)

• The serialization is the JSON-LD specified in the documentation (1)
  • Other JSON-LD contexts/frames should be supported (3)

• Must document how to use the annotation interface, where the annotations are stored by default, and how to use the server API to retrieve and create annotations (1)

• Ability to search on aspects of the data model (2)
  • username
  • body as a tags
  • body as textual comment (keyword)
  • target text
  • target URL
  • created/modified timestamp

• Ability to annotate other annotations (1)
  • Reply
  • Mark as resolved
  • Tag with arbitrary string
  • Tag from a WG editable controlled list of tags
  • Vote up or down
  • assign issue based features including deadline / milestone, responsibility

• Server must accept non-Hypothes.is clients writing and reading to it (2,3)
  • IRC integration (ala RSSAgent)
  • existing issue tracker service integration (Tracker)
  • spec repository integration (Github)
  • custom clients for specific tasks (status report generator)

• Send notifications about new annotations
  • Via Email
  • Via websockets/WebRTC/HTTP callback
  • To connected IRC clients