# ADR-0003 — W3C Web Annotation mapping: native model or import/export?

- Status: proposed
- Date: 2026-05-24
- Workplan: CE-WP-0001-T07 (stub)

## Context

The PRD mandates compatibility with the W3C Web Annotation Data Model
(FR-009 of `wiki/ProductRequirementsDocument.md`). `Selector` shapes already
mirror the W3C taxonomy. Open question: do we serialize our internal types
*as* JSON-LD Web Annotations natively, or maintain our own JSON shape with
an import/export mapping?

The choice affects: storage format, the public API of `evidence-source`'s
ingest/export paths, what "compatible" means when a user imports an existing
W3C annotation collection, and how much our internal model can diverge from
the spec (e.g. our `EvidenceItem` has no W3C analogue).

## Options

- **A. Native JSON-LD as the canonical store**
  - Pros: maximally interoperable; no mapping layer to keep in sync.
  - Cons: JSON-LD adds verbosity and context resolution; our extensions
    (EvidenceItem, EvidenceLink, EvidenceSet) need custom JSON-LD contexts.
    Bad fit for an in-memory MVP.

- **B. Internal model + import/export mapping** *(currently assumed)*
  - Pros: terse internal types; clean fit for `wiki/SharedContracts.md`.
    Mapping only runs at the system boundary.
  - Cons: two shapes to maintain; subtle divergence risk.

- **C. Hybrid — internal model that is a strict superset of W3C JSON shape**
  - Pros: serializes losslessly to W3C without a full JSON-LD context.
  - Cons: ties internal naming to W3C naming forever, which constrains
    future extensions.

## Decision

(blank — required before evidence-source ships its first export path.)

## Consequences

(blank)