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

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
}