Add output validation against a defined JSON schema
This commit is contained in:
145
schema/output.go
Normal file
145
schema/output.go
Normal file
@@ -0,0 +1,145 @@
|
||||
package schema
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"embed"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"sync"
|
||||
|
||||
"github.com/santhosh-tekuri/jsonschema/v6"
|
||||
)
|
||||
|
||||
//go:embed output.schema.json
|
||||
var schemaFS embed.FS
|
||||
|
||||
const outputSchemaPath = "output.schema.json"
|
||||
|
||||
var (
|
||||
compiledOutputSchema *jsonschema.Schema
|
||||
compileOnce sync.Once
|
||||
compileErr error
|
||||
)
|
||||
|
||||
// Transcript is seriatim's public JSON output contract.
|
||||
type Transcript struct {
|
||||
Metadata Metadata `json:"metadata"`
|
||||
Segments []Segment `json:"segments"`
|
||||
OverlapGroups []OverlapGroup `json:"overlap_groups"`
|
||||
}
|
||||
|
||||
// Metadata records the pipeline configuration that produced an artifact.
|
||||
type Metadata struct {
|
||||
Application string `json:"application"`
|
||||
Version string `json:"version"`
|
||||
InputReader string `json:"input_reader"`
|
||||
InputFiles []string `json:"input_files"`
|
||||
PreprocessingModules []string `json:"preprocessing_modules"`
|
||||
PostprocessingModules []string `json:"postprocessing_modules"`
|
||||
OutputModules []string `json:"output_modules"`
|
||||
}
|
||||
|
||||
// Segment is the public transcript segment shape.
|
||||
type Segment struct {
|
||||
ID int `json:"id"`
|
||||
Source string `json:"source"`
|
||||
SourceSegmentIndex *int `json:"source_segment_index,omitempty"`
|
||||
SourceRef string `json:"source_ref,omitempty"`
|
||||
DerivedFrom []string `json:"derived_from,omitempty"`
|
||||
Speaker string `json:"speaker"`
|
||||
Start float64 `json:"start"`
|
||||
End float64 `json:"end"`
|
||||
Text string `json:"text"`
|
||||
Categories []string `json:"categories,omitempty"`
|
||||
OverlapGroupID int `json:"overlap_group_id,omitempty"`
|
||||
}
|
||||
|
||||
// OverlapGroup describes a detected overlapping speech region.
|
||||
type OverlapGroup struct {
|
||||
ID int `json:"id"`
|
||||
Start float64 `json:"start"`
|
||||
End float64 `json:"end"`
|
||||
Segments []string `json:"segments"`
|
||||
Speakers []string `json:"speakers"`
|
||||
Class string `json:"class"`
|
||||
Resolution string `json:"resolution"`
|
||||
}
|
||||
|
||||
// ValidateTranscript validates a typed transcript against the public JSON
|
||||
// schema and seriatim-specific semantic rules.
|
||||
func ValidateTranscript(transcript Transcript) error {
|
||||
if err := validateSemantics(transcript); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
data, err := json.Marshal(transcript)
|
||||
if err != nil {
|
||||
return fmt.Errorf("marshal transcript for schema validation: %w", err)
|
||||
}
|
||||
return ValidateJSON(data)
|
||||
}
|
||||
|
||||
// ValidateJSON validates serialized output JSON against the public schema.
|
||||
func ValidateJSON(data []byte) error {
|
||||
var value any
|
||||
decoder := json.NewDecoder(bytes.NewReader(data))
|
||||
decoder.UseNumber()
|
||||
if err := decoder.Decode(&value); err != nil {
|
||||
return fmt.Errorf("decode output JSON for schema validation: %w", err)
|
||||
}
|
||||
|
||||
compiled, err := outputSchema()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if err := compiled.Validate(value); err != nil {
|
||||
return fmt.Errorf("output schema validation failed: %w", err)
|
||||
}
|
||||
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
|
||||
}
|
||||
|
||||
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
|
||||
}
|
||||
|
||||
func validateSemantics(transcript Transcript) 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)
|
||||
}
|
||||
}
|
||||
for index, group := range transcript.OverlapGroups {
|
||||
if group.End < group.Start {
|
||||
return fmt.Errorf("overlap_group %d has end %.3f before start %.3f", index, group.End, group.Start)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
98
schema/output.schema.json
Normal file
98
schema/output.schema.json
Normal file
@@ -0,0 +1,98 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://gitea.maximumdirect.net/eric/seriatim/schema/output.schema.json",
|
||||
"title": "seriatim output transcript",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["metadata", "segments", "overlap_groups"],
|
||||
"properties": {
|
||||
"metadata": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"application",
|
||||
"version",
|
||||
"input_reader",
|
||||
"input_files",
|
||||
"preprocessing_modules",
|
||||
"postprocessing_modules",
|
||||
"output_modules"
|
||||
],
|
||||
"properties": {
|
||||
"application": { "type": "string" },
|
||||
"version": { "type": "string" },
|
||||
"input_reader": { "type": "string" },
|
||||
"input_files": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"preprocessing_modules": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"postprocessing_modules": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"output_modules": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"segments": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/$defs/segment" }
|
||||
},
|
||||
"overlap_groups": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/$defs/overlap_group" }
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"segment": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "source", "speaker", "start", "end", "text"],
|
||||
"properties": {
|
||||
"id": { "type": "integer", "minimum": 1 },
|
||||
"source": { "type": "string" },
|
||||
"source_segment_index": { "type": "integer", "minimum": 0 },
|
||||
"source_ref": { "type": "string" },
|
||||
"derived_from": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"speaker": { "type": "string" },
|
||||
"start": { "type": "number" },
|
||||
"end": { "type": "number" },
|
||||
"text": { "type": "string" },
|
||||
"categories": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"overlap_group_id": { "type": "integer", "minimum": 1 }
|
||||
}
|
||||
},
|
||||
"overlap_group": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["id", "start", "end", "segments", "speakers", "class", "resolution"],
|
||||
"properties": {
|
||||
"id": { "type": "integer", "minimum": 1 },
|
||||
"start": { "type": "number" },
|
||||
"end": { "type": "number" },
|
||||
"segments": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"speakers": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" }
|
||||
},
|
||||
"class": { "type": "string" },
|
||||
"resolution": { "type": "string" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
191
schema/output_test.go
Normal file
191
schema/output_test.go
Normal file
@@ -0,0 +1,191 @@
|
||||
package schema
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestValidateTranscriptAcceptsValidTranscript(t *testing.T) {
|
||||
transcript := validTranscript()
|
||||
|
||||
if err := ValidateTranscript(transcript); err != nil {
|
||||
t.Fatalf("validate transcript: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestValidateJSONRejectsMissingRequiredField(t *testing.T) {
|
||||
err := ValidateJSON([]byte(`{
|
||||
"metadata": {
|
||||
"application": "seriatim",
|
||||
"version": "dev",
|
||||
"input_reader": "json-files",
|
||||
"input_files": [],
|
||||
"preprocessing_modules": [],
|
||||
"postprocessing_modules": [],
|
||||
"output_modules": []
|
||||
},
|
||||
"segments": []
|
||||
}`))
|
||||
assertErrorContains(t, err, "overlap_groups")
|
||||
}
|
||||
|
||||
func TestValidateJSONRejectsWrongFieldType(t *testing.T) {
|
||||
err := ValidateJSON([]byte(`{
|
||||
"metadata": {
|
||||
"application": "seriatim",
|
||||
"version": "dev",
|
||||
"input_reader": "json-files",
|
||||
"input_files": [],
|
||||
"preprocessing_modules": [],
|
||||
"postprocessing_modules": [],
|
||||
"output_modules": []
|
||||
},
|
||||
"segments": [
|
||||
{
|
||||
"id": "1",
|
||||
"source": "input.json",
|
||||
"speaker": "Alice",
|
||||
"start": 1,
|
||||
"end": 2,
|
||||
"text": "hello"
|
||||
}
|
||||
],
|
||||
"overlap_groups": []
|
||||
}`))
|
||||
assertErrorContains(t, err, "id")
|
||||
}
|
||||
|
||||
func TestValidateJSONRejectsUnexpectedInternalFields(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
field string
|
||||
}{
|
||||
{name: "internal ref", field: `"internal_ref": "internal-1",`},
|
||||
{name: "words", field: `"words": [],`},
|
||||
}
|
||||
|
||||
for _, test := range tests {
|
||||
t.Run(test.name, func(t *testing.T) {
|
||||
err := ValidateJSON([]byte(`{
|
||||
"metadata": {
|
||||
"application": "seriatim",
|
||||
"version": "dev",
|
||||
"input_reader": "json-files",
|
||||
"input_files": [],
|
||||
"preprocessing_modules": [],
|
||||
"postprocessing_modules": [],
|
||||
"output_modules": []
|
||||
},
|
||||
"segments": [
|
||||
{
|
||||
"id": 1,
|
||||
` + test.field + `
|
||||
"source": "input.json",
|
||||
"speaker": "Alice",
|
||||
"start": 1,
|
||||
"end": 2,
|
||||
"text": "hello"
|
||||
}
|
||||
],
|
||||
"overlap_groups": []
|
||||
}`))
|
||||
assertErrorContains(t, err, "additional properties")
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestValidateTranscriptRejectsMissingOrNonSequentialIDs(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 := validTranscript()
|
||||
transcript.Segments = transcript.Segments[:0]
|
||||
for index, id := range test.ids {
|
||||
transcript.Segments = append(transcript.Segments, Segment{
|
||||
ID: id,
|
||||
Source: "input.json",
|
||||
Speaker: "Alice",
|
||||
Start: float64(index),
|
||||
End: float64(index) + 1,
|
||||
Text: "hello",
|
||||
})
|
||||
}
|
||||
|
||||
err := ValidateTranscript(transcript)
|
||||
assertErrorContains(t, err, test.want)
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestValidateTranscriptRejectsInvalidTiming(t *testing.T) {
|
||||
transcript := validTranscript()
|
||||
transcript.Segments[0].Start = 2
|
||||
transcript.Segments[0].End = 1
|
||||
|
||||
err := ValidateTranscript(transcript)
|
||||
assertErrorContains(t, err, "segment 0 has end")
|
||||
}
|
||||
|
||||
func TestValidateTranscriptRejectsInvalidOverlapGroupTiming(t *testing.T) {
|
||||
transcript := validTranscript()
|
||||
transcript.OverlapGroups = []OverlapGroup{
|
||||
{
|
||||
ID: 1,
|
||||
Start: 3,
|
||||
End: 2,
|
||||
Segments: []string{"input.json#0"},
|
||||
Speakers: []string{"Alice"},
|
||||
Class: "unknown",
|
||||
Resolution: "unresolved",
|
||||
},
|
||||
}
|
||||
|
||||
err := ValidateTranscript(transcript)
|
||||
assertErrorContains(t, err, "overlap_group 0 has end")
|
||||
}
|
||||
|
||||
func validTranscript() Transcript {
|
||||
sourceIndex := 0
|
||||
return Transcript{
|
||||
Metadata: Metadata{
|
||||
Application: "seriatim",
|
||||
Version: "dev",
|
||||
InputReader: "json-files",
|
||||
InputFiles: []string{"input.json"},
|
||||
PreprocessingModules: []string{"validate-raw", "normalize-speakers", "trim-text"},
|
||||
PostprocessingModules: []string{"assign-ids", "validate-output"},
|
||||
OutputModules: []string{"json"},
|
||||
},
|
||||
Segments: []Segment{
|
||||
{
|
||||
ID: 1,
|
||||
Source: "input.json",
|
||||
SourceSegmentIndex: &sourceIndex,
|
||||
Speaker: "Alice",
|
||||
Start: 1,
|
||||
End: 2,
|
||||
Text: "hello",
|
||||
},
|
||||
},
|
||||
OverlapGroups: []OverlapGroup{},
|
||||
}
|
||||
}
|
||||
|
||||
func assertErrorContains(t *testing.T, err error, want string) {
|
||||
t.Helper()
|
||||
if err == nil {
|
||||
t.Fatalf("expected error containing %q", want)
|
||||
}
|
||||
if !strings.Contains(err.Error(), want) {
|
||||
t.Fatalf("expected error containing %q, got %v", want, err)
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user