audita/docs/architecture/output-schemas.md

Audita Output Schemas

This document describes the built-in transcript output schema registry used by audita process.

Supported schema names

bare-segments

Status:

• implemented
• default output schema

Shape:

• top-level JSON array of transcript segments

Segment fields:

• id
• speaker
• start
• end
• text
• optional categories

Compatibility:

• this preserves the long-standing output shape used by existing consumers.

audita-v1

Status:

• implemented

Shape:

• top-level JSON object:
  • schema: "audita-v1"
  • version: "v1"
  • segments: transcript segment array

Segment fields inside segments match bare-segments segment fields.

Compatibility:

• this is the Audita-native object format with explicit schema/version metadata.

seriatim-intermediate

Status:

• deferred / not implemented

Current behavior:

• selecting seriatim-intermediate fails clearly as an unsupported output schema.

Reason:

• a concrete, repository-backed contract for this schema has not been finalized yet.

Selection

Choose output schema with CLI:

audita process <transcript.json> --glossary <glossary.yaml> --output-schema audita-v1

Or in file config:

version: 1
output:
  schema: audita-v1

Precedence remains:

1. defaults
2. file config
3. environment overrides
4. CLI overrides

--output-schema overrides output.schema when both are supplied.

Output routing behavior

• With --output, transcript JSON is written to file using the selected schema and stdout stays empty on success.
• Without --output, stdout contains transcript JSON only, using the selected schema.
• --report-json writes report JSON to file and does not write report payloads to stdout.

Backward-compatibility expectations

• default schema stays bare-segments for compatibility unless explicitly changed in a future breaking release;
• supported schema names are treated as stable public contract values;
• unsupported schema names fail before output write.