# Pi Reads schemas

The JSON Schemas in `v1/` are the machine-readable form of the Pi Reads product contract. They use JSON Schema draft 2020-12.

Canonical records:

- `source.schema.json` — immutable captured input, provenance, and optional recapture lineage
- `source-content-index.schema.json` — deterministic heading/paragraph locators derived from source Markdown
- `search-index.schema.json` — rebuildable local BM25-style lexical index over article/source metadata and prose
- `article-user-state.schema.json` — mutable, revisioned reading status, tags, rating, priority, and dates kept outside article manifests
- `user-state-snapshot.schema.json` — portable deterministic user-state backup/restore payload
- `portable-snapshot.schema.json` — full-library backup inventory, byte hashes, and strictly allowlisted portable preferences
- `citation.schema.json` — a generated article's reference to a source
- `citation-diagnostics.schema.json` — bounded source-grounding and article-section citation diagnostics
- `generation-template.schema.json` — versioned structured generation templates, immutable snapshots, and budget diagnostics
- `article.schema.json` — an archive, digest, or synthesis reading document with optional backward-compatible coverage/diagnostic metadata
- `collection.schema.json` — an ordered immutable reading pack with article provenance snapshots
- `export.schema.json` — a rendered article/collection artifact and destination attempt
- `config.schema.json` — non-secret user configuration

`common.schema.json` contains shared hashes, timestamps, paths, and stored-file definitions.

All persisted records carry `schemaVersion: 1`. Implementations must validate data at read and write boundaries. A future incompatible format gets a new versioned schema directory and an explicit migration; existing records are never silently rewritten.

See [`../docs/product-contract.md`](../docs/product-contract.md) for semantic rules that cannot be expressed completely in JSON Schema.