notarius/docs/integrations/seriatim.md

Seriatim Minimal Transcript JSON

This document describes the Seriatim input format currently accepted by the seriatim input adapter.

Adapter

• Module key: seriatim
• Document kind: transcript
• Unit kind: transcript_segment
• Source format: application/vnd.seriatim.minimal+json

The adapter parses raw Seriatim JSON into a generic SourceDocument. It does not add transcript-specific fields to core source or runner contracts.

Accepted Shape

The input must be a JSON object with top-level metadata and segments fields:

{
  "metadata": {
    "id": "session-alpha",
    "title": "Synthetic session transcript"
  },
  "segments": [
    {
      "id": "seg-001",
      "start": 0,
      "end": 4.5,
      "speaker": "Narrator",
      "text": "The stone door opens."
    }
  ]
}

Extra compatible fields are ignored. Multiple top-level JSON values are rejected.

Validation

The adapter rejects:

• empty raw input;
• malformed JSON;
• missing, null, or non-object metadata;
• missing, null, non-array, or empty segments;
• empty segment IDs;
• segment IDs with leading or trailing whitespace;
• duplicate segment IDs;
• missing or empty speaker;
• missing, empty, invalid, non-finite, or negative start;
• missing, empty, invalid, non-finite, or negative end;
• end values before start;
• missing or empty text.

Segment text may keep leading or trailing whitespace, but it must not be empty after trimming.

Source Mapping

The adapter maps Seriatim input into the source model as follows:

• top-level metadata becomes SourceDocument.Metadata;
• SourceDocument.Digest is sha256:<hex> of the exact raw input bytes;
• segment.id becomes SourceUnit.ID;
• segment.text becomes SourceUnit.Text;
• each source unit has kind transcript_segment;
• segment speaker, start, and end are stored in source-unit metadata.

SourceDocument.ID is selected in this order:

1. the parse request source ID, after trimming;
2. metadata.id, when it is a non-empty string after trimming;
3. metadata.source_id, when it is a non-empty string after trimming;
4. seriatim:<first-16-hex-chars-of-raw-sha256>.

Metadata Keys

Seriatim unit metadata uses these keys:

• speaker: string speaker label;
• start: json.Number start value;
• end: json.Number end value.

The internal/modules/input/seriatim package provides typed accessors for these metadata values.

Capabilities

The module declares these provided capabilities for pipeline validation:

• source.transcript
• transcript.speaker
• transcript.timestamps

Limits

Only the Seriatim minimal transcript shape described here is supported. Broader Seriatim schema variants are not currently accepted as a compatibility contract.