audita/docs/integrations/transcript-glossary-files.md

Transcript and Glossary File Integration

Scope

This document defines the input file contracts for:

• transcript JSON;
• glossary YAML.

These files are loaded and validated before processing begins.

Transcript JSON Contract

Audita accepts either top-level shape:

• JSON array of segments; or
• JSON object with a segments array.

Segment fields:

• id (optional integer in source form);
• speaker (required non-empty string);
• start (required finite non-negative number);
• end (required finite non-negative number, >= start);
• text (required non-empty string);
• categories (optional string array; entries must be non-empty).

Additional rules:

• transcript must contain at least one segment;
• duplicate segment IDs are rejected when IDs are present.

Example (examples/tiny-transcript.json):

[
  {
    "id": 1,
    "speaker": "A",
    "start": 0.0,
    "end": 1.2,
    "text": "hello world"
  }
]

Glossary YAML Contract

Audita expects top-level glossary list entries.

Entry fields:

• name (required non-empty string);
• category (required non-empty string);
• summary (required non-empty string);
• aliases (optional list of strings; entries must be non-empty);
• plural (optional string).

Additional rules:

• glossary must contain at least one entry.

Example (examples/tiny-glossary.yaml):

glossary:
  - name: Audita
    aliases:
      - audita
    category: product
    summary: The Audita transcript correction CLI.

Validation Failure Behavior

Representative transcript validation failures:

• invalid JSON;
• unsupported top-level shape;
• empty speaker or text;
• invalid times (NaN, Inf, negative, or end < start);
• duplicate IDs;
• empty transcript array.

Representative glossary validation failures:

• invalid YAML;
• empty or missing glossary entries;
• missing required entry fields;
• empty alias values.

These failures surface as schema errors and the process exits nonzero.

CLI Usage

Minimal invocation:

audita process ./transcript.json --glossary ./glossary.yaml --output ./corrected.json

See also:

• docs/cli.md
• docs/config.md
• examples/tiny-transcript.json
• examples/tiny-glossary.yaml