An annotation is useful only when its meaning and target can be recovered
The W3C Web Annotation model separates the annotation, body, target, selector, state and motivation so comments, tags and links can travel between systems without losing what they refer to.
Highlighting a sentence looks simple until the page changes. A useful annotation must identify what is being said, what resource or segment it concerns, why the relationship exists, who asserted it and which representation was observed.
Web Annotation provides a shared graph for those decisions. It can target an entire resource or a precisely selected part, attach embedded or external bodies, express motivations such as commenting or tagging, and preserve enough context for a receiving system to interpret the claim.
Chapter contents
- 1. Start with the annotation relationship
- 2. Use motivation to state why the body applies
- 3. Target a whole resource before reaching for selectors
- 4. Use Fragment Selectors when a registered fragment syntax fits
- 5. Choose Text Quote and Text Position Selectors deliberately
- 6. Worked example: annotate a sentence and an image region
- 7. Use SVG, Data Position and refined selectors only when justified
- 8. Use State to identify the observed representation
- 9. Preserve provenance, attribution and confidence
- 10. Design re-anchoring and orphan handling as normal states
- 11. Validate syntax, semantics and client behaviour separately
- 12. Audit privacy, moderation, rights and portability
Choose a reading route
- Route 1: Read the graph — annotation, body, target and motivation
- Route 2: Select precisely — fragments, positions and quotes
- Route 3: Work an example — text, image and layered selectors
- Route 4: Survive change — states, provenance and re-anchoring
- Route 5: Publish and audit — validation, privacy and transfer
How to use this guide
Start with the chapters that match your immediate decision, then return to the worked example and audit chapters. Each chapter separates a model from the evidence needed to use it responsibly. A claim is not strengthened merely by being technical; it is strengthened when assumptions, observations, alternatives and limits can be inspected.
| Layer | Question | Minimum record |
|---|---|---|
| Concept | What exactly is being represented? | Definitions and boundary |
| Method | How will the reasoning be carried out? | Steps, inputs and assumptions |
| Transfer | Would it work in a changed setting? | A deliberately altered case |
| Audit | What could prove it wrong? | Evidence, limits and revision trigger |
Chapter 1. Start with the annotation relationship
The idea
A Web Annotation is a first-class resource that relates one or more bodies to one or more targets. The annotation carries the assertion; the body supplies the content or resource being applied; the target identifies what the assertion concerns.
A disciplined method
Draw three nodes before serialising anything. Give the annotation its own identity when it must be cited, versioned or shared, then record body and target roles explicitly.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is whether the body is the message, evidence, tag or linked resource. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A reviewer annotation has a textual body saying “definition needed” and targets one paragraph in a report.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Change the body from embedded text to a maintained glossary URI and state what remains the annotation’s assertion.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: The graph records a relationship but does not prove the body is true or the target was interpreted correctly.
Evidence to retain: annotation identifier, body value or URI, target identity, creator and created time
Common misconception: The comment itself is the annotation and therefore needs no separate relationship.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 2. Use motivation to state why the body applies
The idea
Motivation expresses the intended relationship, such as commenting, tagging, describing, linking, classifying or supplementing. It lets clients choose suitable presentation without guessing from body content.
A disciplined method
Select the narrowest standard motivation that matches the visible purpose, document any extension term and test how a basic client behaves when it does not recognise that term.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which behaviour a receiving client should infer from the relationship. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A short keyword body with tagging motivation can appear in a tag facet; the same word with commenting motivation belongs in discussion.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Transfer the annotation to a transcription workflow and compare describing, supplementing and commenting.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Motivation is an asserted purpose, not a guarantee that every client will render it identically.
Evidence to retain: motivation URI, local definition, client matrix and fallback display
Common misconception: Clients can reliably infer motivation from whether the body is short or long.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 3. Target a whole resource before reaching for selectors
The idea
A direct target URI means the body applies to the resource as a whole. Specific Resources and Selectors are needed only when the assertion concerns a segment, representation or state.
A disciplined method
Ask whether the assertion would remain correct for every part and representation. Use a direct target if yes; otherwise describe a Specific Resource and its source plus selector.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is whether precision changes the claim rather than merely the interface. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A licence note targets a complete dataset; a correction targets one table cell and needs a more specific target.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Change a paragraph comment into a document-wide editorial note and remove unnecessary selector complexity.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: A whole-resource target can become ambiguous when a URI serves changing or negotiated representations.
Evidence to retain: target URI, representation metadata, scope note and retrieval test
Common misconception: Every annotation needs a selector to be precise.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 4. Use Fragment Selectors when a registered fragment syntax fits
The idea
A Fragment Selector carries a fragment value interpreted according to a specification such as media fragments. It reuses a known addressing convention rather than inventing coordinates.
A disciplined method
Record the fragment value and conformsTo specification, verify it against the retrieved media type and test more than one conforming client.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which fragment specification and representation give the value meaning. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
An image annotation targets xywh=100,200,400,300 under the W3C Media Fragments specification.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Replace the image with a derivative at different dimensions and test whether pixel coordinates still select the intended region.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Fragments can depend on representation dimensions, format support and client implementation.
Evidence to retain: fragment string, conformsTo URI, source dimensions, media type and screenshot
Common misconception: A fragment value is self-explanatory and portable without its governing specification.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 5. Choose Text Quote and Text Position Selectors deliberately
The idea
Text Quote Selectors anchor by exact text with optional prefix and suffix; Text Position Selectors anchor by start and end offsets. Quotes tolerate some movement, while positions can be efficient but brittle after edits.
A disciplined method
Normalise text consistently, record exact and contextual strings, define the counting convention for positions and combine selectors only when the application can interpret the refinement.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which change the anchor must survive and which ambiguity is acceptable. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
The quote “shared model” appears twice, so prefix and suffix disambiguate it; positions accelerate lookup in the saved edition.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Insert a paragraph above the target and compare quote and position recovery.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Repeated text, normalisation differences and content edits can defeat either method.
Evidence to retain: source snapshot, normalisation rules, quote context, offsets and re-anchoring result
Common misconception: Quotes always survive edits while positions never do.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 6. Worked example: annotate a sentence and an image region
The idea
A complete small graph can show two target types while keeping annotation identities, bodies, motivations and evidence separate.
A disciplined method
Create one commenting annotation on a sentence with a Text Quote Selector and one describing annotation on an image region with a Fragment Selector. Validate JSON-LD and open both in a second client.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is whether each selector resolves against the exact source representation used. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A fictional report sentence receives a correction; its chart receives a description of one bar. Each annotation records creator, created time and source state.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Revise the sentence and resize the chart, then document which anchor resolves, which is re-anchored and which becomes orphaned.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: The example demonstrates information architecture, not the accuracy or rights status of the fictional content.
Evidence to retain: original sources, annotation JSON, selector tests, client screenshots and revision log
Common misconception: If an annotation renders once, its target will remain stable.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
| Annotation | Body | Target method |
|---|---|---|
| Correction | Embedded TextualBody | Text Quote plus context |
| Chart note | External description | Media Fragment xywh |
| Document note | Policy URI | Whole resource |
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 7. Use SVG, Data Position and refined selectors only when justified
The idea
The model offers selector types for shapes, byte ranges and nested refinement. Extra precision is useful only when the source and consuming software share the same coordinate or data assumptions.
A disciplined method
Document coordinate space, encoding, byte order, transforms and refinement sequence; include a simpler fallback when loss of detail is preferable to total failure.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which representation-level assumptions are stable enough to publish. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
An SVG polygon marks an irregular map region; a Data Position Selector marks bytes in a fixed archival file.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Serve a transcoded version and test whether the byte selector or SVG coordinate system remains meaningful.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Complex selectors have uneven client support and can create false confidence in geometric accuracy.
Evidence to retain: source fixity, encoding, dimensions, selector order and compatibility tests
Common misconception: More detailed geometry always produces a more interoperable annotation.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 8. Use State to identify the observed representation
The idea
A State can describe the time or representation at which a source should be interpreted. TimeState and HttpRequestState help distinguish an annotation on a historical version from one on whatever the URI returns today.
A disciplined method
Capture an archived representation or fixity where possible, record the retrieval time and HTTP request context when material, and state the policy for later source changes.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is whether the claim is about a resource identity or one observed representation. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A news-page annotation records the source as retrieved on a date and links to an archived copy.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Change content negotiation language and test whether the same selector resolves on each representation.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: A timestamp does not guarantee that the historical bytes can still be retrieved.
Evidence to retain: retrieval time, headers, archived URI, checksum and resolution result
Common misconception: Adding a TimeState automatically preserves the source version.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 9. Preserve provenance, attribution and confidence
The idea
Creator, created, generated, source and rights information let readers distinguish who made an annotation, which tool generated it and whether later edits changed the assertion.
A disciplined method
Separate human creator from generator software, preserve original creation and modification times, link source evidence and state uncertainty in visible body text when it matters.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is who is accountable for the assertion and who merely transmitted it. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A classifier proposes a tag; an editor accepts it. The annotation records the tool as generator and the editor as creator or reviewer according to policy.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Transfer to an imported annotation whose original creator cannot be verified; retain attribution as a claim rather than upgrading it to authenticated identity.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Metadata can record provenance claims but cannot authenticate them without external controls.
Evidence to retain: account identifiers, signatures where used, version history, review action and source chain
Common misconception: A creator field proves that the named person made and endorsed the annotation.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 10. Design re-anchoring and orphan handling as normal states
The idea
Targets change, disappear or become inaccessible. A robust system distinguishes resolved, migrated, ambiguous and orphaned annotations instead of silently attaching comments to the wrong passage.
A disciplined method
Resolve exact identifiers first, apply bounded fallback selectors, score ambiguity, require review for close matches and retain the original target description.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is when automated re-anchoring is safe enough to accept. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A changed paragraph contains the quote twice after editing; the system marks the annotation ambiguous rather than choosing the first match.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Move the source across domains with redirects and compare identifier, quote and archived-state recovery.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: No re-anchoring algorithm can reconstruct author intent when source context has been destroyed.
Evidence to retain: old and new source versions, candidate anchors, confidence, reviewer decision and migration map
Common misconception: An approximate match is better than an orphaned annotation.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 11. Validate syntax, semantics and client behaviour separately
The idea
Valid JSON is not necessarily valid JSON-LD or a conforming annotation, and a conforming annotation may expose client limitations. Each layer needs a distinct check.
A disciplined method
Parse JSON, expand JSON-LD, validate required types and properties, dereference body and target resources, then exercise representative clients and accessibility paths.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which failure belongs to data, source availability or viewer support. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A Text Quote Selector validates but the client ignores prefix and suffix, producing an ambiguous highlight.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Remove network access to external bodies and test whether the annotation remains understandable.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Conformance does not establish truth, relevance, safety or long-term persistence.
Evidence to retain: validator version, expanded graph, HTTP trace, client matrix and accessibility review
Common misconception: If one browser extension displays the highlight, the annotation is interoperable.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Chapter 12. Audit privacy, moderation, rights and portability
The idea
Annotations can expose reading activity, sensitive locations, personal allegations and copyrighted extracts. Portability requires governance as well as a shared data model.
A disciplined method
Classify body and target sensitivity, minimise stored context, obtain authority to publish, moderate harmful content, preserve takedown and correction routes and export without hidden dependencies.
A useful working record makes the sequence visible: first state the question and unit of analysis; next record the observations and their provenance; then apply the stated rule; finally compare the result with plausible alternatives. For this chapter, the decisive choice is which information should travel with the annotation and which should remain access-controlled. Keeping that choice explicit prevents a later reader from mistaking a convenient convention for a fact about the world.
Worked example
A learning platform exports teacher feedback but excludes private reading telemetry and limits quoted source text.
Work the example twice. On the first pass, follow the stated assumptions. On the second, reverse one assumption, remove one piece of evidence and ask whether the conclusion, ranking or boundary changes. This small stress test matters because polished outputs can hide sensitivity. The objective is not to force certainty; it is to locate the evidence on which the conclusion actually turns.
Changed-context transfer check
Move annotations from a private classroom to a public repository and reassess consent, context and harm.
A transfer succeeds only when the structure of the problem survives the change. Match roles, dependencies and measurement conditions rather than surface vocabulary. Record what was preserved, what changed, and why the method still applies—or why it does not. If the new context changes the data-generating process or the people bearing the burden, re-specify the model instead of importing the old answer.
Limits, evidence and revision
Limit: Technical interoperability cannot override privacy, defamation, copyright or safeguarding duties.
Evidence to retain: consent or authority, access rules, moderation record, rights basis, export test and remedy path
Common misconception: Open annotation data should include every context field because reuse is always beneficial.
A gold-standard conclusion is therefore conditional. It should name the observation period, excluded cases, uncertainty and the event that would trigger review. Negative findings and unresolved contradictions belong in the record. They protect future readers from repeating a hidden assumption and make correction possible without reconstructing the entire analysis from memory.
Practical evidence check
Can another reader recover the input, reproduce the intermediate decision and identify at least one observation that would change the result? If not, the chapter has produced an explanation but not yet an auditable finding.
Field workbook
Annotate one paragraph and one image from a rights-cleared source. Use two different selectors, record the observed source state, validate the JSON-LD, revise the source and document resolution, ambiguity or orphaning.
- Write the decision question in one sentence and name the decision owner.
- List observations separately from interpretations, with dates and provenance.
- Record at least two plausible alternatives before choosing a preferred account.
- Run the changed-context test and note which assumptions fail.
- State the limit, confidence and next review trigger in plain language.
| Layer | Evidence | Failure signal |
|---|---|---|
| Relationship | Body, target and motivation | Client guesses purpose |
| Anchor | Selector and source state | Wrong or orphaned target |
| Provenance | Creator, generator and version | Attribution collapses |
| Transfer | Second-client test | Valid data is unusable |
Continue through the verified ecosystem
- IIIF presentation objects — Annotation Pages and Canvas targets
- OAI-ORE resource maps — resource boundaries and contextual identity
- Data citation — versioned sources and fixity
- Canonical serialization — stable bytes and signature verification
Frequently asked questions
What is the difference between a body and a target?
The body is the content or resource being applied; the target is what that content concerns.
When should I use a selector?
Use one when the annotation concerns a segment or representation rather than the whole source.
Which text selector is most robust?
It depends on change patterns. Quotes can survive movement; positions are efficient for a fixed edition; combining evidence can improve recovery.
What does motivation do?
It states why the body is related to the target, such as commenting, tagging or describing.
Does TimeState archive a page?
No. It records a temporal context; preservation still requires an accessible historical representation.
Can every valid annotation render everywhere?
No. Client support for selectors, motivations and external resources varies and must be tested.
Authoritative sources and further reading
- W3C Web Annotation Data Model — authoritative body, target, selector, state and motivation model
- W3C Web Annotation Vocabulary — RDF vocabulary and JSON-LD context
- W3C Selectors and States — reusable selector and state definitions
- W3C Media Fragments URI 1.0 — temporal and spatial fragment semantics
- W3C JSON-LD 1.1 — linked-data serialization and processing
This guide explains information architecture for annotations. It does not determine the truth of an assertion, clear rights or replace privacy, moderation and preservation policy.