# Creator/Reviewer JSON Schemas

This reference describes the JSON payloads written by the creator and reviewer steps in the review loop.

## Schema source and file locations

- Schema helpers: `src/podcast_pipeline/protocol_schemas.py` (backed by models in `src/podcast_pipeline/domain/models.py`).
- Creator candidate files: `copy/candidates/<asset_id>/candidate_<uuid>.json`.
- Reviewer iteration files: `copy/reviews/<asset_id>/iteration_XX.<reviewer>.json` (or `iteration_XX.json` if the
  reviewer name is omitted).

## Creator candidate (Candidate)

Required fields:

- `asset_id` (string, pattern `[a-z][a-z0-9_]*`)
- `content` (string)

Optional or filled by the system:

- `candidate_id` (UUID)
- `format` (`markdown` | `plain` | `html`, default `markdown`)
- `created_at` (ISO 8601 timestamp)
- `provenance` (list of provenance entries)

Provenance entry fields:

- Required: `kind`, `ref`
- Optional: `created_at`, `metadata`

## Reviewer iteration (ReviewIteration)

Required fields:

- `iteration` (integer >= 1)
- `verdict` (`ok` | `changes_requested` | `needs_human`)

Optional or filled by the system:

- `issues` (list of issue objects)
- `reviewer` (string or null)
- `created_at` (ISO 8601 timestamp)
- `summary` (string or null)
- `provenance` (list of provenance entries)

Issue entry fields:

- Required: `message`
- Optional: `issue_id` (UUID), `severity` (`error` | `warning`), `code`, `field`

Constraints:

- `verdict=ok` cannot include issues with `severity=error`.