seriatim/schema/output.go

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
}