Add output validation against a defined JSON schema

schema/output.go

@@ -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
+}