notarius/docs/integrations/seriatim.md

Seriatim Transcript JSON

This document is the external input contract consumed by the production Seriatim input adapter. Selectable input-adapter keys are cataloged in Configuration.

Adapter

• Source format: application/vnd.seriatim+json

Accepted Shape

The input must be one JSON object with top-level metadata and segments fields. This covers the maintained minimal fixture and Seriatim intermediate output that provides the same required segment fields.

The maintained example is examples/seriatim-minimal-transcript.json.

Required top-level fields:

• metadata: an object. Its entries are accepted as source metadata.
• segments: a non-empty array of segment objects.

Required segment fields:

• id: a positive integer JSON number or canonical decimal string without leading zeros or surrounding whitespace;
• start: a finite, non-negative JSON number or numeric string;
• end: a finite, non-negative JSON number or numeric string that is not less than start;
• speaker: a non-empty string;
• text: a non-empty string.

Other top-level and segment fields, such as categories, are ignored.

Multiple top-level JSON values are rejected.

Validation

The adapter rejects empty input, malformed JSON, multiple top-level JSON values, non-object segment values, duplicate segment IDs, and any violation of the shape or field constraints above.

Segment text is preserved as provided, but it must not be empty after trimming.

Derived Identity

Notarius identifies the parsed source in this order:

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

The exact raw input SHA-256 remains the basis of the fallback source ID. The source digest recorded in output provenance is instead the SHA-256 of the canonical generic source document, excluding the digest field itself. It covers the derived source identity, document kind and format, ordered units and their self-references, and accepted metadata. Segment IDs become the unit IDs used by artifact source references; each produced unit carries a self-reference whose source ID is the derived document ID and whose start and end IDs both equal the segment ID.

Compatibility Limit

This contract covers only Seriatim transcript JSON with the top-level metadata object and segments array described here. Broader Seriatim output schemas are compatible only when they provide these required fields with the accepted types.