# Output Schemas

## Scope

seriatim emits one of three public JSON output contracts:

- `seriatim-minimal`
- `seriatim-intermediate`
- `seriatim-full`

These are used by `merge`, `trim`, and `normalize`, and are accepted as input
by `render`.

## Schema roles

`seriatim-minimal`:

- compact metadata plus ordered transcript segments
- no source/provenance fields
- no overlap groups

`seriatim-intermediate`:

- compact metadata plus ordered segments
- includes optional segment `categories`
- no source/provenance fields
- no overlap groups

`seriatim-full`:

- full metadata (`input_reader`, module lists, input files, output modules)
- source/provenance fields on segments
- overlap-group data
- version metadata populated from build info (`internal/buildinfo`)

## Semantic invariants

All schema outputs enforce:

- segment IDs are sequential starting at `1`
- segment timing uses `end >= start`

Full schema also enforces overlap-group timing (`end >= start`).

## Validation APIs

Go package: `gitea.maximumdirect.net/eric/seriatim/schema`

Key validators:

- `schema.ValidateMinimalTranscript`
- `schema.ValidateIntermediateTranscript`
- `schema.ValidateTranscript`
- `schema.ValidateMinimalJSON`
- `schema.ValidateIntermediateJSON`
- `schema.ValidateJSON`

## Machine-readable schema files

- [../../schema/minimal-output.schema.json](../../schema/minimal-output.schema.json)
- [../../schema/intermediate-output.schema.json](../../schema/intermediate-output.schema.json)
- [../../schema/full-output.schema.json](../../schema/full-output.schema.json)

## Related docs and examples

- CLI reference: [../cli.md](../cli.md)
- Artifact internals: [../internal/artifacts.md](../internal/artifacts.md)
- Trim example input artifact:
  - [../../examples/trim/input-full.json](../../examples/trim/input-full.json)