Notes and Annotations

People need to write things about a law: a comment explaining a term, a link from a sentence to the rule that executes it, a flag on an ambiguous norm. The hard part is that law text changes. Articles get renumbered, sentences get reworded, and a note pinned to “article 2, character 140” breaks the moment an article is inserted above it.

RegelRecht keeps notes stand-off: stored separately from the law, never embedded in it, so the verbatim source text stays untouched. A note anchors to the text by quoting it, following the W3C Web Annotation Data Model.

Anchoring by quote

A note targets text through a TextQuoteSelector: the exact quote, plus a little prefix and suffix for context. From a real note on the Wet op de zorgtoeslag (corpus/annotations/wet_op_de_zorgtoeslag/annotations.yaml):

Because the anchor is the content, not a line number, the note follows its text. Insert a new article 1a and renumber the target to 4a, and the note still lands on 4a. The resolver (packages/engine/src/annotation/) reports one of three outcomes (MatchStatus):

• Found: exactly one location matches.
• Ambiguous: the quote occurs more than once with no context to separate the hits (the common word “verzekerde” three times in a sentence). Adding a prefix or suffix disambiguates.
• Orphaned: the text is gone. The note is not silently dropped; it is marked orphaned so a human can re-anchor it.

When wording drifts slightly (a Staatsblad amendment swaps a few words), exact matching fails but fuzzy matching recovers it: normalized Levenshtein similarity above a threshold (currently 0.7) resolves as a fuzzy match with a confidence below 1.0; a wholesale rewrite falls below the threshold and orphans rather than mis-anchoring. A note may also carry an optional article hint to try first; an outdated hint falls back to a full search. The behavior is pinned by features/notes.feature.

What a note says

The motivation field is the kind of note. The W3C model defines thirteen motivation values (Web Annotation Data Model, §3.3.5); four matter for law work, and three of those are in use in the corpus today:

• linking ties a sentence to the machine_readable element that executes it, making the chain from text to logic auditable.
• commenting is a plain explanation for readers.
• questioning flags an open or ambiguous norm. These draw their term from a controlled vocabulary (corpus/annotations/_vocabulary/ambiguity.yaml) and move through a small workflow: an open question becomes resolved once the implementing regulation is found and modelled.

The fourth, tagging (classification), is available but not yet used in the corpus.

Storage, federation, and authority

Notes live in sidecar YAML keyed by the law’s $id, not its file path (corpus/annotations/{law_id}/annotations.yaml). They follow the same federated model as the corpus: any organization can keep notes on a law in its own repository, and the editor’s write path is append-only so parallel edits do not clobber each other.

A note’s authority is derived at display time, not declared. The resolver compares the note’s creator against the article’s competent authority:

• authoritative when the creator is the competent body itself (Dienst Toeslagen on its own act).
• advisory when the creator is another government organization.
• generated when tooling produced it.
• personal when an individual wrote it.

The same note text means something different depending on who wrote it, and the model makes that explicit instead of treating every note as equal.

The engine exposes resolution to the browser through the WASM bindings resolveNote and resolveNotes (packages/engine/src/wasm.rs), so the editor anchors notes against the live text on screen.

Further reading

• Competent Authority - the basis for a note’s derived authority
• Federated Corpus - how notes are distributed
• RFC-005: Stand-off Notes and RFC-018: Note Infrastructure - full specifications