70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# 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](../config.md#implemented-production-modules).
|
|
|
|
## 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](../../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.
|