From cc80a123efd6bf88ba225d0ceb8b5464f0bf8249 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 28 Apr 2026 21:32:43 -0500 Subject: [PATCH] Added a new JSON public schema as the default output artifact --- README.md | 32 +++++- architecture.md | 2 +- internal/artifact/transcript.go | 29 ++++++ internal/artifact/transcript_test.go | 51 ++++++++++ internal/builtin/postprocess.go | 2 + internal/builtin/postprocess_test.go | 33 ++++++ internal/cli/merge.go | 2 +- internal/cli/merge_test.go | 93 +++++++++++++++++ internal/config/config.go | 7 +- internal/config/config_test.go | 46 ++++++++- schema/default-output.schema.json | 42 ++++++++ schema/output.go | 60 ++++++++++- schema/output.schema.json | 2 +- schema/output_test.go | 144 +++++++++++++++++++++++++++ 14 files changed, 533 insertions(+), 12 deletions(-) create mode 100644 schema/default-output.schema.json diff --git a/README.md b/README.md index b58e08c..ce30a1f 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ Global flags: | `--autocorrect` | No | none | Autocorrect rules YAML file. When omitted, the default `autocorrect` module leaves text unchanged. | | `--input-reader` | No | `json-files` | Input reader module. | | `--output-modules` | No | `json` | Comma-separated output modules. | -| `--output-schema` | No | `seriatim` | JSON output contract. Allowed values are `seriatim` and `minimal`. | +| `--output-schema` | No | `default` | JSON output contract. Allowed values are `default`, `minimal`, and `seriatim`. | | `--preprocessing-modules` | No | `validate-raw,normalize-speakers,trim-text` | Comma-separated preprocessing modules, evaluated in order. | | `--postprocessing-modules` | No | `detect-overlaps,resolve-overlaps,backchannel,filler,resolve-danglers,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output` | Comma-separated postprocessing modules, evaluated in order. | | `--coalesce-gap` | No | `3.0` | Maximum same-speaker gap in seconds for `coalesce`; also used as the `resolve-overlaps` context window. Must be a non-negative float. | @@ -159,7 +159,29 @@ The old `inputs:` direct mapping format is no longer supported. `--output-modules json` controls the writer. `--output-schema` controls the JSON contract that writer serializes. -The default `seriatim` schema uses the full seriatim envelope: +The `default` schema is the default output contract. It stays close to `minimal`, but adds optional `categories` on each segment: + +```json +{ + "metadata": { + "application": "seriatim", + "version": "dev", + "output_schema": "default" + }, + "segments": [ + { + "id": 1, + "start": 1.25, + "end": 3.5, + "speaker": "Eric Rakestraw", + "text": "Hello there.", + "categories": ["backchannel"] + } + ] +} +``` + +The explicit `seriatim` schema uses the full seriatim envelope: ```json { @@ -230,7 +252,9 @@ The `minimal` schema emits minimal metadata and compact ordered segments: } ``` -Minimal output intentionally omits overlap groups, categories, source/provenance fields, and pipeline configuration metadata. +Minimal output intentionally omits categories, overlap groups, source/provenance fields, and pipeline configuration metadata. + +Default output intentionally omits overlap groups and source/provenance fields, but keeps optional `categories` and minimal metadata. Segments are sorted deterministically by: @@ -246,7 +270,7 @@ The public Go output contract is available from: import "gitea.maximumdirect.net/eric/seriatim/schema" ``` -The same package embeds machine-readable JSON Schemas in `schema/output.schema.json` and `schema/minimal-output.schema.json`. The default `validate-output` postprocessor validates the selected output shape and verifies final segment IDs are present, sequential, and start at `1`. +The same package embeds machine-readable JSON Schemas in `schema/output.schema.json`, `schema/default-output.schema.json`, and `schema/minimal-output.schema.json`. The default `validate-output` postprocessor validates the selected output shape and verifies final segment IDs are present, sequential, and start at `1`. ## Overlap Detection diff --git a/architecture.md b/architecture.md index 9f5e011..4d3608b 100644 --- a/architecture.md +++ b/architecture.md @@ -216,7 +216,7 @@ seriatim merge \ --preprocessing-modules validate-raw,normalize-speakers,trim-text \ --postprocessing-modules detect-overlaps,resolve-overlaps,backchannel,filler,resolve-danglers,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output \ --output-modules json \ - --output-schema seriatim \ + --output-schema default \ --output-file merged.json \ --report-file report.json ``` diff --git a/internal/artifact/transcript.go b/internal/artifact/transcript.go index 1e8b5e2..ec6d51c 100644 --- a/internal/artifact/transcript.go +++ b/internal/artifact/transcript.go @@ -57,6 +57,31 @@ func FromMerged(cfg config.Config, merged model.MergedTranscript) schema.Transcr } } +// DefaultFromMerged converts the internal merged transcript model into the +// compact default public serialized output contract. +func DefaultFromMerged(cfg config.Config, merged model.MergedTranscript) schema.DefaultTranscript { + segments := make([]schema.DefaultSegment, len(merged.Segments)) + for index, segment := range merged.Segments { + segments[index] = schema.DefaultSegment{ + ID: segment.ID, + Start: segment.Start, + End: segment.End, + Speaker: segment.Speaker, + Text: segment.Text, + Categories: append([]string(nil), segment.Categories...), + } + } + + return schema.DefaultTranscript{ + Metadata: schema.DefaultMetadata{ + Application: ApplicationName, + Version: buildinfo.Version, + OutputSchema: config.OutputSchemaDefault, + }, + Segments: segments, + } +} + // MinimalFromMerged converts the internal merged transcript model into the // compact public serialized output contract. func MinimalFromMerged(cfg config.Config, merged model.MergedTranscript) schema.MinimalTranscript { @@ -85,8 +110,12 @@ func MinimalFromMerged(cfg config.Config, merged model.MergedTranscript) schema. // runtime-selected public output contract. func SelectedFromMerged(cfg config.Config, merged model.MergedTranscript) any { switch cfg.OutputSchema { + case config.OutputSchemaDefault: + return DefaultFromMerged(cfg, merged) case config.OutputSchemaMinimal: return MinimalFromMerged(cfg, merged) + case config.OutputSchemaSeriatim: + return FromMerged(cfg, merged) default: return FromMerged(cfg, merged) } diff --git a/internal/artifact/transcript_test.go b/internal/artifact/transcript_test.go index 087b3d6..542c72f 100644 --- a/internal/artifact/transcript_test.go +++ b/internal/artifact/transcript_test.go @@ -30,6 +30,57 @@ func TestSelectedFromMergedDefaultsToSeriatimTranscript(t *testing.T) { } } +func TestSelectedFromMergedUsesDefaultWhenConfigured(t *testing.T) { + got := SelectedFromMerged(config.Config{OutputSchema: config.OutputSchemaDefault}, model.MergedTranscript{}) + if _, ok := got.(schema.DefaultTranscript); !ok { + t.Fatalf("selected artifact type = %T, want schema.DefaultTranscript", got) + } +} + +func TestSelectedFromMergedUsesSeriatimWhenConfigured(t *testing.T) { + got := SelectedFromMerged(config.Config{OutputSchema: config.OutputSchemaSeriatim}, model.MergedTranscript{}) + if _, ok := got.(schema.Transcript); !ok { + t.Fatalf("selected artifact type = %T, want schema.Transcript", got) + } +} + +func TestDefaultFromMergedEmitsOnlyDefaultShape(t *testing.T) { + merged := model.MergedTranscript{ + Segments: []model.Segment{ + { + ID: 1, + Source: "input.json", + SourceRef: "word-run:1:1:1", + DerivedFrom: []string{"input.json#0"}, + Speaker: "Alice", + Start: 1, + End: 2, + Text: "hello", + Categories: []string{"backchannel"}, + OverlapGroupID: 1, + }, + }, + OverlapGroups: []model.OverlapGroup{ + {ID: 1, Start: 1, End: 2, Segments: []string{"input.json#0"}, Speakers: []string{"Alice"}, Class: "unknown", Resolution: "unresolved"}, + }, + } + + got := DefaultFromMerged(config.Config{OutputSchema: config.OutputSchemaDefault}, merged) + want := schema.DefaultTranscript{ + Metadata: schema.DefaultMetadata{ + Application: ApplicationName, + Version: buildinfo.Version, + OutputSchema: config.OutputSchemaDefault, + }, + Segments: []schema.DefaultSegment{ + {ID: 1, Start: 1, End: 2, Speaker: "Alice", Text: "hello", Categories: []string{"backchannel"}}, + }, + } + if !reflect.DeepEqual(got, want) { + t.Fatalf("default transcript = %#v, want %#v", got, want) + } +} + func TestMinimalFromMergedEmitsOnlyMinimalShape(t *testing.T) { merged := model.MergedTranscript{ Segments: []model.Segment{ diff --git a/internal/builtin/postprocess.go b/internal/builtin/postprocess.go index f4d056a..bc4b830 100644 --- a/internal/builtin/postprocess.go +++ b/internal/builtin/postprocess.go @@ -51,6 +51,8 @@ func (validateOutput) Process(ctx context.Context, in model.MergedTranscript, cf selected := artifact.SelectedFromMerged(cfg, in) var err error switch transcript := selected.(type) { + case schema.DefaultTranscript: + err = schema.ValidateDefaultTranscript(transcript) case schema.MinimalTranscript: err = schema.ValidateMinimalTranscript(transcript) case schema.Transcript: diff --git a/internal/builtin/postprocess_test.go b/internal/builtin/postprocess_test.go index afbaaa6..0dae8c0 100644 --- a/internal/builtin/postprocess_test.go +++ b/internal/builtin/postprocess_test.go @@ -81,6 +81,38 @@ func TestValidateOutputUsesMinimalSchemaWhenConfigured(t *testing.T) { } } +func TestValidateOutputUsesSeriatimSchemaWhenConfigured(t *testing.T) { + merged := model.MergedTranscript{ + Segments: []model.Segment{ + { + ID: 1, + Source: "input.json", + SourceRef: "word-run:1:1:1", + DerivedFrom: []string{"input.json#0"}, + Speaker: "Alice", + Start: 1, + End: 2, + Text: "hello", + Categories: []string{"backchannel"}, + OverlapGroupID: 1, + }, + }, + } + + cfg := testConfig() + cfg.OutputSchema = config.OutputSchemaSeriatim + got, events, err := validateOutput{}.Process(context.Background(), merged, cfg) + if err != nil { + t.Fatalf("validate output: %v", err) + } + if len(got.Segments) != 1 { + t.Fatalf("segment count = %d, want 1", len(got.Segments)) + } + if len(events) != 1 || !strings.Contains(events[0].Message, "validated 1 output segment(s)") { + t.Fatalf("events = %#v", events) + } +} + func TestValidateOutputMinimalFailsBeforeAssignIDs(t *testing.T) { merged := model.MergedTranscript{ Segments: []model.Segment{ @@ -103,6 +135,7 @@ func testConfig() config.Config { return config.Config{ InputReader: config.DefaultInputReader, InputFiles: []string{"input.json"}, + OutputSchema: config.DefaultOutputSchema, PreprocessingModules: []string{"validate-raw", "normalize-speakers", "trim-text"}, PostprocessingModules: []string{"assign-ids", "validate-output"}, OutputModules: []string{"json"}, diff --git a/internal/cli/merge.go b/internal/cli/merge.go index 9e0a0f2..f9e9127 100644 --- a/internal/cli/merge.go +++ b/internal/cli/merge.go @@ -32,7 +32,7 @@ func newMergeCommand() *cobra.Command { flags.StringVar(&opts.AutocorrectFile, "autocorrect", "", "autocorrect rules file") flags.StringVar(&opts.InputReader, "input-reader", config.DefaultInputReader, "input reader module") flags.StringVar(&opts.OutputModules, "output-modules", config.DefaultOutputModules, "comma-separated output modules") - flags.StringVar(&opts.OutputSchema, "output-schema", config.DefaultOutputSchema, "output JSON schema: seriatim or minimal") + flags.StringVar(&opts.OutputSchema, "output-schema", config.DefaultOutputSchema, "output JSON schema: default, minimal, or seriatim") flags.StringVar(&opts.PreprocessingModules, "preprocessing-modules", config.DefaultPreprocessingModules, "comma-separated preprocessing modules") flags.StringVar(&opts.PostprocessingModules, "postprocessing-modules", config.DefaultPostprocessingModules, "comma-separated postprocessing modules") flags.StringVar(&opts.CoalesceGap, "coalesce-gap", config.DefaultCoalesceGapValue, "maximum same-speaker gap in seconds for coalesce") diff --git a/internal/cli/merge_test.go b/internal/cli/merge_test.go index 64b289d..d863a5b 100644 --- a/internal/cli/merge_test.go +++ b/internal/cli/merge_test.go @@ -114,6 +114,81 @@ func TestMergeWritesMergedOutputAndReport(t *testing.T) { } } +func TestMergeWritesDefaultOutputSchema(t *testing.T) { + dir := t.TempDir() + input := writeJSONFile(t, dir, "input.json", `{ + "segments": [ + {"start": 1, "end": 1.6, "text": "yeah"} + ] + }`) + output := filepath.Join(dir, "merged.json") + + err := executeMergeRaw( + "--input-file", input, + "--output-file", output, + ) + if err != nil { + t.Fatalf("merge failed: %v", err) + } + + var transcript schema.DefaultTranscript + readJSON(t, output, &transcript) + if transcript.Metadata.OutputSchema != config.OutputSchemaDefault { + t.Fatalf("output_schema = %q, want default", transcript.Metadata.OutputSchema) + } + if len(transcript.Segments) != 1 { + t.Fatalf("segment count = %d, want 1", len(transcript.Segments)) + } + segment := transcript.Segments[0] + if len(segment.Categories) != 1 || segment.Categories[0] != "backchannel" { + t.Fatalf("categories = %#v, want [backchannel]", segment.Categories) + } + outputBytes, err := os.ReadFile(output) + if err != nil { + t.Fatalf("read output: %v", err) + } + for _, forbidden := range []string{"overlap_groups", "source", "derived_from", "words"} { + if strings.Contains(string(outputBytes), forbidden) { + t.Fatalf("default output contains %q:\n%s", forbidden, outputBytes) + } + } +} + +func TestMergeWritesSeriatimOutputSchema(t *testing.T) { + dir := t.TempDir() + input := writeJSONFile(t, dir, "input.json", `{ + "segments": [ + {"start": 1, "end": 1.6, "text": "yeah"} + ] + }`) + output := filepath.Join(dir, "merged.json") + + err := executeMergeRaw( + "--input-file", input, + "--output-file", output, + "--output-schema", "seriatim", + ) + if err != nil { + t.Fatalf("merge failed: %v", err) + } + + var transcript model.FinalTranscript + readJSON(t, output, &transcript) + if len(transcript.Segments) != 1 { + t.Fatalf("segment count = %d, want 1", len(transcript.Segments)) + } + segment := transcript.Segments[0] + if len(segment.Categories) != 1 || segment.Categories[0] != "backchannel" { + t.Fatalf("categories = %#v, want [backchannel]", segment.Categories) + } + if segment.Source == "" { + t.Fatal("expected full output to include source") + } + if len(transcript.OverlapGroups) != 0 { + t.Fatalf("expected no overlap groups, got %d", len(transcript.OverlapGroups)) + } +} + func TestMergeWritesMinimalOutputSchema(t *testing.T) { dir := t.TempDir() input := writeJSONFile(t, dir, "input.json", `{ @@ -1916,11 +1991,29 @@ func TestInvalidTimingFails(t *testing.T) { } func executeMerge(args ...string) error { + if !hasOutputSchemaFlag(args) { + // Most integration tests were written against the full envelope; keep + // that behavior unless the caller explicitly asks for another schema. + args = append(args, "--output-schema", config.OutputSchemaSeriatim) + } + return executeMergeRaw(args...) +} + +func executeMergeRaw(args ...string) error { cmd := NewRootCommand() cmd.SetArgs(append([]string{"merge"}, args...)) return cmd.Execute() } +func hasOutputSchemaFlag(args []string) bool { + for _, arg := range args { + if arg == "--output-schema" { + return true + } + } + return false +} + func writeJSONFile(t *testing.T, dir string, name string, content string) string { t.Helper() diff --git a/internal/config/config.go b/internal/config/config.go index 3a5a12a..4e67754 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -13,7 +13,7 @@ import ( const ( DefaultInputReader = "json-files" DefaultOutputModules = "json" - DefaultOutputSchema = OutputSchemaSeriatim + DefaultOutputSchema = OutputSchemaDefault DefaultPreprocessingModules = "validate-raw,normalize-speakers,trim-text" DefaultPostprocessingModules = "detect-overlaps,resolve-overlaps,backchannel,filler,resolve-danglers,coalesce,detect-overlaps,autocorrect,assign-ids,validate-output" DefaultOverlapWordRunGap = 0.75 @@ -26,6 +26,7 @@ const ( WordRunReorderWindowEnv = "SERIATIM_OVERLAP_WORD_RUN_REORDER_WINDOW" BackchannelMaxDurationEnv = "SERIATIM_BACKCHANNEL_MAX_DURATION" FillerMaxDurationEnv = "SERIATIM_FILLER_MAX_DURATION" + OutputSchemaDefault = "default" OutputSchemaSeriatim = "seriatim" OutputSchemaMinimal = "minimal" ) @@ -188,10 +189,10 @@ func parseModuleList(value string) ([]string, error) { func validateOutputSchema(value string) error { switch value { - case OutputSchemaSeriatim, OutputSchemaMinimal: + case OutputSchemaDefault, OutputSchemaSeriatim, OutputSchemaMinimal: return nil default: - return fmt.Errorf("--output-schema must be one of %q or %q", OutputSchemaSeriatim, OutputSchemaMinimal) + return fmt.Errorf("--output-schema must be one of %q, %q, or %q", OutputSchemaDefault, OutputSchemaMinimal, OutputSchemaSeriatim) } } diff --git a/internal/config/config_test.go b/internal/config/config_test.go index 787a214..29d10dd 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -46,7 +46,7 @@ func TestDuplicateInputFilesFailValidation(t *testing.T) { } } -func TestOutputSchemaDefaultsToSeriatim(t *testing.T) { +func TestOutputSchemaDefaultsToDefault(t *testing.T) { dir := t.TempDir() input := writeTempFile(t, dir, "input.json") output := filepath.Join(dir, "merged.json") @@ -67,6 +67,28 @@ func TestOutputSchemaDefaultsToSeriatim(t *testing.T) { } } +func TestOutputSchemaAcceptsDefault(t *testing.T) { + dir := t.TempDir() + input := writeTempFile(t, dir, "input.json") + output := filepath.Join(dir, "merged.json") + + cfg, err := NewMergeConfig(MergeOptions{ + InputFiles: []string{input}, + OutputFile: output, + InputReader: DefaultInputReader, + OutputModules: DefaultOutputModules, + OutputSchema: OutputSchemaDefault, + PreprocessingModules: DefaultPreprocessingModules, + PostprocessingModules: DefaultPostprocessingModules, + }) + if err != nil { + t.Fatalf("config failed: %v", err) + } + if cfg.OutputSchema != OutputSchemaDefault { + t.Fatalf("output schema = %q, want %q", cfg.OutputSchema, OutputSchemaDefault) + } +} + func TestOutputSchemaAcceptsMinimal(t *testing.T) { dir := t.TempDir() input := writeTempFile(t, dir, "input.json") @@ -89,6 +111,28 @@ func TestOutputSchemaAcceptsMinimal(t *testing.T) { } } +func TestOutputSchemaAcceptsSeriatim(t *testing.T) { + dir := t.TempDir() + input := writeTempFile(t, dir, "input.json") + output := filepath.Join(dir, "merged.json") + + cfg, err := NewMergeConfig(MergeOptions{ + InputFiles: []string{input}, + OutputFile: output, + InputReader: DefaultInputReader, + OutputModules: DefaultOutputModules, + OutputSchema: OutputSchemaSeriatim, + PreprocessingModules: DefaultPreprocessingModules, + PostprocessingModules: DefaultPostprocessingModules, + }) + if err != nil { + t.Fatalf("config failed: %v", err) + } + if cfg.OutputSchema != OutputSchemaSeriatim { + t.Fatalf("output schema = %q, want %q", cfg.OutputSchema, OutputSchemaSeriatim) + } +} + func TestOutputSchemaRejectsUnknownValue(t *testing.T) { dir := t.TempDir() input := writeTempFile(t, dir, "input.json") diff --git a/schema/default-output.schema.json b/schema/default-output.schema.json new file mode 100644 index 0000000..352727d --- /dev/null +++ b/schema/default-output.schema.json @@ -0,0 +1,42 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://gitea.maximumdirect.net/eric/seriatim/schema/default-output.schema.json", + "title": "seriatim default output transcript", + "type": "object", + "additionalProperties": false, + "required": ["metadata", "segments"], + "properties": { + "metadata": { + "type": "object", + "additionalProperties": false, + "required": ["application", "version", "output_schema"], + "properties": { + "application": { "type": "string" }, + "version": { "type": "string" }, + "output_schema": { "type": "string", "const": "default" } + } + }, + "segments": { + "type": "array", + "items": { "$ref": "#/$defs/segment" } + } + }, + "$defs": { + "segment": { + "type": "object", + "additionalProperties": false, + "required": ["id", "start", "end", "speaker", "text"], + "properties": { + "id": { "type": "integer", "minimum": 1 }, + "start": { "type": "number" }, + "end": { "type": "number" }, + "speaker": { "type": "string" }, + "text": { "type": "string" }, + "categories": { + "type": "array", + "items": { "type": "string" } + } + } + } + } +} diff --git a/schema/output.go b/schema/output.go index 4510563..d3fb451 100644 --- a/schema/output.go +++ b/schema/output.go @@ -15,6 +15,7 @@ var schemaFS embed.FS const ( outputSchemaPath = "output.schema.json" + defaultOutputSchemaPath = "default-output.schema.json" minimalOutputSchemaPath = "minimal-output.schema.json" ) @@ -24,13 +25,19 @@ var ( compileMu sync.Mutex ) -// Transcript is seriatim's public JSON output contract. +// Transcript is seriatim's full public JSON output contract. type Transcript struct { Metadata Metadata `json:"metadata"` Segments []Segment `json:"segments"` OverlapGroups []OverlapGroup `json:"overlap_groups"` } +// DefaultTranscript is seriatim's default public JSON output contract. +type DefaultTranscript struct { + Metadata DefaultMetadata `json:"metadata"` + Segments []DefaultSegment `json:"segments"` +} + // MinimalTranscript is seriatim's compact public JSON output contract. type MinimalTranscript struct { Metadata MinimalMetadata `json:"metadata"` @@ -48,6 +55,13 @@ type Metadata struct { OutputModules []string `json:"output_modules"` } +// DefaultMetadata records default artifact identity. +type DefaultMetadata struct { + Application string `json:"application"` + Version string `json:"version"` + OutputSchema string `json:"output_schema"` +} + // MinimalMetadata records minimal artifact identity. type MinimalMetadata struct { Application string `json:"application"` @@ -70,6 +84,17 @@ type Segment struct { OverlapGroupID int `json:"overlap_group_id,omitempty"` } +// DefaultSegment is the compact public transcript segment shape with +// categories. +type DefaultSegment struct { + ID int `json:"id"` + Start float64 `json:"start"` + End float64 `json:"end"` + Speaker string `json:"speaker"` + Text string `json:"text"` + Categories []string `json:"categories,omitempty"` +} + // MinimalSegment is the compact public transcript segment shape. type MinimalSegment struct { ID int `json:"id"` @@ -104,6 +129,20 @@ func ValidateTranscript(transcript Transcript) error { return ValidateJSON(data) } +// ValidateDefaultTranscript validates the default transcript against the +// default JSON schema and seriatim-specific semantic rules. +func ValidateDefaultTranscript(transcript DefaultTranscript) error { + if err := validateDefaultSemantics(transcript); err != nil { + return err + } + + data, err := json.Marshal(transcript) + if err != nil { + return fmt.Errorf("marshal default transcript for schema validation: %w", err) + } + return ValidateDefaultJSON(data) +} + // ValidateMinimalTranscript validates a minimal transcript against the minimal // JSON schema and seriatim-specific semantic rules. func ValidateMinimalTranscript(transcript MinimalTranscript) error { @@ -123,6 +162,12 @@ func ValidateJSON(data []byte) error { return validateJSONWithSchema(data, outputSchemaPath) } +// ValidateDefaultJSON validates serialized default output JSON against the +// default public schema. +func ValidateDefaultJSON(data []byte) error { + return validateJSONWithSchema(data, defaultOutputSchemaPath) +} + // ValidateMinimalJSON validates serialized minimal output JSON against the // minimal public schema. func ValidateMinimalJSON(data []byte) error { @@ -200,6 +245,19 @@ func validateSemantics(transcript Transcript) error { return nil } +func validateDefaultSemantics(transcript DefaultTranscript) 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 +} + func validateMinimalSemantics(transcript MinimalTranscript) error { for index, segment := range transcript.Segments { wantID := index + 1 diff --git a/schema/output.schema.json b/schema/output.schema.json index 4266233..867b69c 100644 --- a/schema/output.schema.json +++ b/schema/output.schema.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://gitea.maximumdirect.net/eric/seriatim/schema/output.schema.json", - "title": "seriatim output transcript", + "title": "seriatim full output transcript", "type": "object", "additionalProperties": false, "required": ["metadata", "segments", "overlap_groups"], diff --git a/schema/output_test.go b/schema/output_test.go index 11ca295..2b811c1 100644 --- a/schema/output_test.go +++ b/schema/output_test.go @@ -21,6 +21,14 @@ func TestValidateMinimalTranscriptAcceptsValidTranscript(t *testing.T) { } } +func TestValidateDefaultTranscriptAcceptsValidTranscript(t *testing.T) { + transcript := validDefaultTranscript() + + if err := ValidateDefaultTranscript(transcript); err != nil { + t.Fatalf("validate default transcript: %v", err) + } +} + func TestValidateMinimalJSONRejectsMissingRequiredField(t *testing.T) { err := ValidateMinimalJSON([]byte(`{ "metadata": { @@ -103,6 +111,81 @@ func TestValidateMinimalJSONRejectsUnexpectedFields(t *testing.T) { } } +func TestValidateDefaultJSONRejectsMissingRequiredField(t *testing.T) { + err := ValidateDefaultJSON([]byte(`{ + "metadata": { + "application": "seriatim", + "version": "dev", + "output_schema": "default" + } + }`)) + assertErrorContains(t, err, "segments") +} + +func TestValidateDefaultJSONRejectsWrongFieldType(t *testing.T) { + err := ValidateDefaultJSON([]byte(`{ + "metadata": { + "application": "seriatim", + "version": "dev", + "output_schema": "default" + }, + "segments": [ + { + "id": "1", + "start": 1, + "end": 2, + "speaker": "Alice", + "text": "hello" + } + ] + }`)) + assertErrorContains(t, err, "id") +} + +func TestValidateDefaultJSONRejectsUnexpectedFields(t *testing.T) { + tests := []struct { + name string + json string + }{ + { + name: "top-level overlap groups", + json: `{ + "metadata": {"application": "seriatim", "version": "dev", "output_schema": "default"}, + "segments": [], + "overlap_groups": [] + }`, + }, + { + name: "segment source", + json: `{ + "metadata": {"application": "seriatim", "version": "dev", "output_schema": "default"}, + "segments": [{"id": 1, "source": "input.json", "start": 1, "end": 2, "speaker": "Alice", "text": "hello"}] + }`, + }, + { + name: "segment derived from", + json: `{ + "metadata": {"application": "seriatim", "version": "dev", "output_schema": "default"}, + "segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "derived_from": ["input.json#0"]}] + }`, + }, + { + name: "segment words", + json: `{ + "metadata": {"application": "seriatim", "version": "dev", "output_schema": "default"}, + "segments": [{"id": 1, "start": 1, "end": 2, "speaker": "Alice", "text": "hello", "words": []}] + }`, + }, + } + + for _, test := range tests { + t.Run(test.name, func(t *testing.T) { + err := ValidateDefaultJSON([]byte(test.json)) + assertErrorContains(t, err, "additional properties") + }) + } +} + func TestValidateJSONRejectsMissingRequiredField(t *testing.T) { err := ValidateJSON([]byte(`{ "metadata": { @@ -184,6 +267,46 @@ func TestValidateJSONRejectsUnexpectedInternalFields(t *testing.T) { } } +func TestValidateDefaultTranscriptRejectsMissingOrNonSequentialIDs(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 := validDefaultTranscript() + transcript.Segments = transcript.Segments[:0] + for index, id := range test.ids { + transcript.Segments = append(transcript.Segments, DefaultSegment{ + ID: id, + Start: float64(index), + End: float64(index) + 1, + Speaker: "Alice", + Text: "hello", + }) + } + + err := ValidateDefaultTranscript(transcript) + assertErrorContains(t, err, test.want) + }) + } +} + +func TestValidateDefaultTranscriptRejectsInvalidTiming(t *testing.T) { + transcript := validDefaultTranscript() + transcript.Segments[0].Start = 2 + transcript.Segments[0].End = 1 + + err := ValidateDefaultTranscript(transcript) + assertErrorContains(t, err, "segment 0 has end") +} + func TestValidateTranscriptRejectsMissingOrNonSequentialIDs(t *testing.T) { tests := []struct { name string @@ -302,6 +425,26 @@ func validMinimalTranscript() MinimalTranscript { } } +func validDefaultTranscript() DefaultTranscript { + return DefaultTranscript{ + Metadata: DefaultMetadata{ + Application: "seriatim", + Version: "dev", + OutputSchema: "default", + }, + Segments: []DefaultSegment{ + { + ID: 1, + Start: 1, + End: 2, + Speaker: "Alice", + Text: "hello", + Categories: []string{"backchannel"}, + }, + }, + } +} + func validTranscript() Transcript { sourceIndex := 0 return Transcript{ @@ -323,6 +466,7 @@ func validTranscript() Transcript { Start: 1, End: 2, Text: "hello", + Categories: []string{"backchannel"}, }, }, OverlapGroups: []OverlapGroup{},