# Citations

<!-- GENERATED by common/bin/file-schemas-docs.ts from the schemas and their *_FIELD_DOCS records — do not edit by hand. -->

The one citation model, for every document that cites the corpus: a report (`report.json` — see [REPORT.md](REPORT.md)), a standalone citation set (`archilyzer-citations`, below), and whatever comes next. The schema is `common/lib/citations/schema.ts`; the value rules are `common/lib/citations/validate.ts`, which reports every problem with its JSON path instead of stopping at the first.

A citation is a discriminated union on `kind`: `video` and `audio` (a span of a record's media), `post` (a post record), `source` (a sentence of a document under review) and `page` (a web page outside the corpus). Every kind carries the common fields. A container names its citations by id in a `citations` map, and its documents in a `sources` map; an id is letters, digits and `_ . : -`, starting with a letter or digit, at most 64, and no id names both a source and a citation. Unknown keys are refused, and so is an unknown kind: a new kind is a new version.

**Citing inline.** In any markdown a document carries, `[label](cite:<id>)` cites the citation `<id>` (a link inside a code span or a fenced block is text, not a citation). Citations are numbered per document by first appearance in reading order — a citation cited again keeps its number — and each has the stable anchor `#c-<id>`.

**Moments.** A `video` or `audio` citation opens the page `/m/<channel>/<id>/<start>-<end>/`, a `post` citation `/m/<channel>/<id>/`; `source` and `page` citations have no page of their own. `<start>` and `<end>` are written with two decimals, always (`12.50`, never `12.5`), so a moment has one URL; the pad is not part of it. `<channel>` and `<id>` are single safe path segments (letters, digits, `.`, `_`, `-`; a channel starts with a letter or digit, an id may start with `-`). Moment keys are `common/lib/citations/moments.ts`.

**Spans.** `start` is at least 0, `end` is after it (by at least 0.01 s), each `pad` is at least 0, and the span with its pad is at most 120 s.

**Paths.** A still (`image`) or a saved document (`saved`) is relative to the container's directory: `/`-separated, never absolute, with no empty, `.` or `..` segment.

Regenerate this file with `pnpm --filter yt-dlp-transcript-common exec tsx bin/file-schemas-docs.ts`.

## Every kind

#### Common fields

| Key | Required | Description |
|---|---|---|
| `quote` | yes | The cited words, VERBATIM — as the record says them (a span's cues, a post's text, the source's sentence, the page's text). Never a paraphrase: compose checks a span's quote against its cues and fails on drift. |
| `speaker` | no | Who says the quote, when that is not the record's own channel (a guest, a co-host, a caller). |
| `date` | no | When the quote was said or written: `YYYY`, `YYYY-MM`, `YYYY-MM-DD` or an ISO 8601 date-time. Absent = the record's own date. |
| `label` | no | A short display name for the citation (one line), used where its number alone would be too little. |
| `note` | no | An editorial note shown with the citation (plain text): context the quote needs. |
| `origin` | no | In a report that reviews a document (`subject`): where this evidence came from. `"subject"` — the document itself gave it (its link, its embedded clip, its picture); `"added"` — the report's author found it, the document did not give it. Absent = not known. A report with no `subject` carries none. |
| `verification` | no | COMPUTED, not authored: what checking this citation found, written by compose. A hand-typed block that could not have come from a check (a score outside 0–1, a score without its time) is a validation problem. |

#### `verification`

| Key | Required | Description |
|---|---|---|
| `quoteScore` | no | How closely `quote` matches what the record says at the cited place, from 0 (nothing alike) to 1 (verbatim). Written by the check, with `quoteCheckedAt`. |
| `quoteCheckedAt` | no | When the quote was checked: an ISO 8601 date-time. Written with `quoteScore`. |
| `voiceChecked` | no | True when the speaker's voice in the cited span was checked against `speaker`. Only a span (video, audio) has a voice to check. |
| `method` | no | What did the checking, e.g. the cue-window comparison and its version. Free text, one line. |

## The kinds

#### `"video"`

| Key | Required | Description |
|---|---|---|
| `kind` | yes | `"video"`. |
| `channel` | yes | The record's channel slug (its directory under `transcripts/channels/`). A path segment of the moment page. |
| `id` | yes | The record's video id (its directory under `data/`; may start with `-`). A path segment of the moment page. |
| `start` | yes | Where the cited span starts, in seconds from the start of the record. |
| `end` | yes | Where the cited span ends, in seconds; after `start`. |
| `pad` | no | Context around the span in the evidence clip, in seconds. Absent = none. The span plus its pad is at most 120 s. |

#### `"audio"`

| Key | Required | Description |
|---|---|---|
| `kind` | yes | `"audio"`: a span of a record with no picture worth showing (a podcast). Rendered with a poster. |
| `channel` | yes | The record's channel slug (its directory under `transcripts/channels/`). A path segment of the moment page. |
| `id` | yes | The record's video id (its directory under `data/`; may start with `-`). A path segment of the moment page. |
| `start` | yes | Where the cited span starts, in seconds from the start of the record. |
| `end` | yes | Where the cited span ends, in seconds; after `start`. |
| `pad` | no | Context around the span in the evidence clip, in seconds. Absent = none. The span plus its pad is at most 120 s. |

#### `pad` (video, audio)

| Key | Required | Description |
|---|---|---|
| `before` | no | Seconds of context before `start`; ≥ 0. Absent = 0. |
| `after` | no | Seconds of context after `end`; ≥ 0. Absent = 0. |

#### `"post"`

| Key | Required | Description |
|---|---|---|
| `kind` | yes | `"post"`. |
| `channel` | yes | The post's channel slug. A path segment of the moment page. |
| `id` | yes | The post's id. A path segment of the moment page. |
| `thread` | no | True to show the post with the thread it belongs to. Absent = the post alone. |

#### `"source"`

| Key | Required | Description |
|---|---|---|
| `kind` | yes | `"source"`: a sentence of a document under review. |
| `source` | yes | The id of the document in the container's `sources`. Its archive links are shown with the citation. |
| `image` | no | A still of the sentence as the document shows it: a path relative to the container's directory (e.g. `stills/a01.png`), never absolute, never leaving it. |

#### `"page"`

| Key | Required | Description |
|---|---|---|
| `kind` | yes | `"page"`: a web page outside the corpus. |
| `url` | yes | The page's address: an http(s) URL. |
| `title` | no | The page's title. |
| `archiveUrl` | no | An archived copy of the page (an http(s) URL), shown beside the live link. |

## Sources

The documents a `source` citation quotes, in a container's `sources` map by id. A saved copy (`saved`) is the input stills are shot from and is never published.

#### `sources.<id>`

| Key | Required | Description |
|---|---|---|
| `kind` | yes | What the document is: `article`, `page`, `video`, `post`, `document`, `other`. |
| `title` | yes | The document's title. |
| `url` | no | Where the document lives: an http(s) URL. |
| `publisher` | no | Who published it (the outlet, the site). |
| `author` | no | Who wrote it. |
| `date` | no | When it was published: `YYYY`, `YYYY-MM`, `YYYY-MM-DD` or an ISO 8601 date-time. |
| `archives` | no | The document's archive links, in context — as the document had them. Shown with every citation of it. |
| `note` | no | A note shown with the document's byline (plain text), e.g. which copy of it was read. |
| `accent` | no | The document's colour, `"#rrggbb"`: the rail beside each of its quoted sentences and the edge of its box, so they read as one source. Absent = the theme's border colour. |
| `saved` | no | A saved copy of the document, relative to the container's directory (e.g. `sources/s0/page.html`): the input the stills are shot from. NEVER published. |

#### `sources.<id>.archives[]`

| Key | Required | Description |
|---|---|---|
| `label` | yes | The link's text. |
| `url` | yes | The archived copy: an http(s) URL. |
| `context` | no | The words around the link in the document, so a reader sees what it was offered as. |

## A citation set

Citations outside a report — what a converter of a sweep, an answer or a video manifest emits — are one JSON document, format `"archilyzer-citations"`, version 1.

#### The document

| Key | Required | Description |
|---|---|---|
| `format` | yes | `"archilyzer-citations"`. |
| `version` | yes | `1`. |
| `sources` | no | The documents the `source` citations quote, by id. Absent = none. |
| `citations` | yes | The citations, by id. An id is what a `[label](cite:<id>)` link names. |