Added a new JSON public schema as the default output artifact

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

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

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"],

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{},