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 }