eric/seriatim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Added support for a minimal JSON output schema

Browse Source
This commit is contained in:
Eric Rakestraw
2026-04-28 14:39:00 -05:00
parent a3ca6665a9
commit 9cca88280f
16 changed files with 658 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
schema/minimal-output.schema.json Normal file
View File

@@ -0,0 +1,38 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://gitea.maximumdirect.net/eric/seriatim/schema/minimal-output.schema.json",
"title": "seriatim minimal output transcript",
"type": "object",
"additionalProperties": false,
"required": ["metadata", "segments"],
"properties": {
"metadata": {
"type": "object",
"additionalProperties": false,
"required": ["application", "version", "output_schema"],
"properties": {
"application": { "type": "string" },
"version": { "type": "string" },
"output_schema": { "type": "string", "const": "minimal" }
}
},
"segments": {
"type": "array",
"items": { "$ref": "#/$defs/segment" }
}
},
"$defs": {
"segment": {
"type": "object",
"additionalProperties": false,
"required": ["id", "start", "end", "speaker", "text"],
"properties": {
"id": { "type": "integer", "minimum": 1 },
"start": { "type": "number" },
"end": { "type": "number" },
"speaker": { "type": "string" },
"text": { "type": "string" }
}
}
}
}

131
schema/output.go
View File

@@ -10,15 +10,18 @@ import (
"github.com/santhosh-tekuri/jsonschema/v6"
)
//go:embed output.schema.json
//go:embed *.schema.json
var schemaFS embed.FS
const outputSchemaPath = "output.schema.json"
const (
outputSchemaPath = "output.schema.json"
minimalOutputSchemaPath = "minimal-output.schema.json"
)
var (
compiledOutputSchema *jsonschema.Schema
compileOnce sync.Once
compileErr error
compiledSchemas = make(map[string]*jsonschema.Schema)
compileErrs = make(map[string]error)
compileMu sync.Mutex
)
// Transcript is seriatim's public JSON output contract.
@@ -28,6 +31,12 @@ type Transcript struct {
OverlapGroups []OverlapGroup `json:"overlap_groups"`
}
// MinimalTranscript is seriatim's compact public JSON output contract.
type MinimalTranscript struct {
Metadata MinimalMetadata `json:"metadata"`
Segments []MinimalSegment `json:"segments"`
}
// Metadata records the pipeline configuration that produced an artifact.
type Metadata struct {
Application string `json:"application"`
@@ -39,6 +48,13 @@ type Metadata struct {
OutputModules []string `json:"output_modules"`
}
// MinimalMetadata records minimal artifact identity.
type MinimalMetadata struct {
Application string `json:"application"`
Version string `json:"version"`
OutputSchema string `json:"output_schema"`
}
// Segment is the public transcript segment shape.
type Segment struct {
ID int `json:"id"`
@@ -54,6 +70,15 @@ type Segment struct {
OverlapGroupID int `json:"overlap_group_id,omitempty"`
}
// MinimalSegment is the compact public transcript segment shape.
type MinimalSegment struct {
ID int `json:"id"`
Start float64 `json:"start"`
End float64 `json:"end"`
Speaker string `json:"speaker"`
Text string `json:"text"`
}
// OverlapGroup describes a detected overlapping speech region.
type OverlapGroup struct {
ID int `json:"id"`
@@ -79,8 +104,32 @@ func ValidateTranscript(transcript Transcript) error {
return ValidateJSON(data)
}
// ValidateMinimalTranscript validates a minimal transcript against the minimal
// JSON schema and seriatim-specific semantic rules.
func ValidateMinimalTranscript(transcript MinimalTranscript) error {
if err := validateMinimalSemantics(transcript); err != nil {
return err
}
data, err := json.Marshal(transcript)
if err != nil {
return fmt.Errorf("marshal minimal transcript for schema validation: %w", err)
}
return ValidateMinimalJSON(data)
}
// ValidateJSON validates serialized output JSON against the public schema.
func ValidateJSON(data []byte) error {
return validateJSONWithSchema(data, outputSchemaPath)
}
// ValidateMinimalJSON validates serialized minimal output JSON against the
// minimal public schema.
func ValidateMinimalJSON(data []byte) error {
return validateJSONWithSchema(data, minimalOutputSchemaPath)
}
func validateJSONWithSchema(data []byte, schemaPath string) error {
var value any
decoder := json.NewDecoder(bytes.NewReader(data))
decoder.UseNumber()
@@ -88,7 +137,7 @@ func ValidateJSON(data []byte) error {
return fmt.Errorf("decode output JSON for schema validation: %w", err)
}
compiled, err := outputSchema()
compiled, err := outputSchema(schemaPath)
if err != nil {
return err
}
@@ -98,32 +147,39 @@ func ValidateJSON(data []byte) error {
return nil
}
func outputSchema() (*jsonschema.Schema, error) {
compileOnce.Do(func() {
data, err := schemaFS.ReadFile(outputSchemaPath)
if err != nil {
compileErr = fmt.Errorf("read embedded output schema: %w", err)
return
}
var schemaDocument any
decoder := json.NewDecoder(bytes.NewReader(data))
decoder.UseNumber()
if err := decoder.Decode(&schemaDocument); err != nil {
compileErr = fmt.Errorf("decode embedded output schema: %w", err)
return
}
func outputSchema(schemaPath string) (*jsonschema.Schema, error) {
compileMu.Lock()
defer compileMu.Unlock()
compiler := jsonschema.NewCompiler()
if err := compiler.AddResource(outputSchemaPath, schemaDocument); err != nil {
compileErr = fmt.Errorf("load embedded output schema: %w", err)
return
}
compiledOutputSchema, compileErr = compiler.Compile(outputSchemaPath)
if compileErr != nil {
compileErr = fmt.Errorf("compile embedded output schema: %w", compileErr)
}
})
return compiledOutputSchema, compileErr
if compiled, exists := compiledSchemas[schemaPath]; exists {
return compiled, compileErrs[schemaPath]
}
data, err := schemaFS.ReadFile(schemaPath)
if err != nil {
compileErrs[schemaPath] = fmt.Errorf("read embedded output schema: %w", err)
return nil, compileErrs[schemaPath]
}
var schemaDocument any
decoder := json.NewDecoder(bytes.NewReader(data))
decoder.UseNumber()
if err := decoder.Decode(&schemaDocument); err != nil {
compileErrs[schemaPath] = fmt.Errorf("decode embedded output schema: %w", err)
return nil, compileErrs[schemaPath]
}
compiler := jsonschema.NewCompiler()
if err := compiler.AddResource(schemaPath, schemaDocument); err != nil {
compileErrs[schemaPath] = fmt.Errorf("load embedded output schema: %w", err)
return nil, compileErrs[schemaPath]
}
compiled, err := compiler.Compile(schemaPath)
if err != nil {
compileErrs[schemaPath] = fmt.Errorf("compile embedded output schema: %w", err)
return nil, compileErrs[schemaPath]
}
compiledSchemas[schemaPath] = compiled
return compiled, nil
}
func validateSemantics(transcript Transcript) error {
@@ -143,3 +199,16 @@ func validateSemantics(transcript Transcript) error {
}
return nil
}
func validateMinimalSemantics(transcript MinimalTranscript) error {
for index, segment := range transcript.Segments {
wantID := index + 1
if segment.ID != wantID {
return fmt.Errorf("segment %d has id %d; want %d", index, segment.ID, wantID)
}
if segment.End < segment.Start {
return fmt.Errorf("segment %d has end %.3f before start %.3f", index, segment.End, segment.Start)
}
}
return nil
}

149
schema/output_test.go
View File

@@ -13,6 +13,96 @@ func TestValidateTranscriptAcceptsValidTranscript(t *testing.T) {
}
}
func TestValidateMinimalTranscriptAcceptsValidTranscript(t *testing.T) {
transcript := validMinimalTranscript()
if err := ValidateMinimalTranscript(transcript); err != nil {
t.Fatalf("validate minimal transcript: %v", err)
}
}
func TestValidateMinimalJSONRejectsMissingRequiredField(t *testing.T) {
err := ValidateMinimalJSON([]byte(`{
"metadata": {
"application": "seriatim",
"version": "dev",
"output_schema": "minimal"
}
}`))
assertErrorContains(t, err, "segments")
}
func TestValidateMinimalJSONRejectsWrongFieldType(t *testing.T) {
err := ValidateMinimalJSON([]byte(`{
"metadata": {
"application": "seriatim",
"version": "dev",
"output_schema": "minimal"
},
"segments": [
{
"id": "1",
"start": 1,
"end": 2,
"speaker": "Alice",
"text": "hello"
}
]
}`))
assertErrorContains(t, err, "id")
}
func TestValidateMinimalJSONRejectsUnexpectedFields(t *testing.T) {
tests := []struct {
name string
json string
}{
{
name: "top-level overlap groups",
json: `{
"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
"segments": [],
"overlap_groups": []
}`,
},
{
name: "segment source",
json: `{
"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
"segments": [{"id": 1, "source": "input.json", "start": 1, "end": 2, "speaker": "Alice", "text": "hello"}]
}`,
},
{
name: "segment categories",
json: `{
"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
"segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "categories": ["backchannel"]}]
}`,
},
{
name: "segment derived from",
json: `{
"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
"segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "derived_from": ["input.json#0"]}]
}`,
},
{
name: "segment words",
json: `{
"metadata": {"application": "seriatim", "version": "dev", "output_schema": "minimal"},
"segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "words": []}]
}`,
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
err := ValidateMinimalJSON([]byte(test.json))
assertErrorContains(t, err, "additional properties")
})
}
}
func TestValidateJSONRejectsMissingRequiredField(t *testing.T) {
err := ValidateJSON([]byte(`{
"metadata": {
@@ -135,6 +225,46 @@ func TestValidateTranscriptRejectsInvalidTiming(t *testing.T) {
assertErrorContains(t, err, "segment 0 has end")
}
func TestValidateMinimalTranscriptRejectsMissingOrNonSequentialIDs(t *testing.T) {
tests := []struct {
name string
ids []int
want string
}{
{name: "missing zero id", ids: []int{0}, want: "segment 0 has id 0; want 1"},
{name: "does not start at one", ids: []int{2}, want: "segment 0 has id 2; want 1"},
{name: "gap", ids: []int{1, 3}, want: "segment 1 has id 3; want 2"},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
transcript := validMinimalTranscript()
transcript.Segments = transcript.Segments[:0]
for index, id := range test.ids {
transcript.Segments = append(transcript.Segments, MinimalSegment{
ID: id,
Start: float64(index),
End: float64(index) + 1,
Speaker: "Alice",
Text: "hello",
})
}
err := ValidateMinimalTranscript(transcript)
assertErrorContains(t, err, test.want)
})
}
}
func TestValidateMinimalTranscriptRejectsInvalidTiming(t *testing.T) {
transcript := validMinimalTranscript()
transcript.Segments[0].Start = 2
transcript.Segments[0].End = 1
err := ValidateMinimalTranscript(transcript)
assertErrorContains(t, err, "segment 0 has end")
}
func TestValidateTranscriptRejectsInvalidOverlapGroupTiming(t *testing.T) {
transcript := validTranscript()
transcript.OverlapGroups = []OverlapGroup{
@@ -153,6 +283,25 @@ func TestValidateTranscriptRejectsInvalidOverlapGroupTiming(t *testing.T) {
assertErrorContains(t, err, "overlap_group 0 has end")
}
func validMinimalTranscript() MinimalTranscript {
return MinimalTranscript{
Metadata: MinimalMetadata{
Application: "seriatim",
Version: "dev",
OutputSchema: "minimal",
},
Segments: []MinimalSegment{
{
ID: 1,
Start: 1,
End: 2,
Speaker: "Alice",
Text: "hello",
},
},
}
}
func validTranscript() Transcript {
sourceIndex := 0
return Transcript{