feat: add line/column positions to JSON and YAML schema errors

Schema validation errors now include source positions, pointing to the
exact line and column of the offending key in the original file.

For JSON, a position map is built by tokenizing the source with
encoding/json.Decoder and tracking byte offsets for each key path.
For YAML, the yaml.v3 Node API provides line/column on every node.

The gojsonschema library reports errors with JSON paths like
"(root).server.port". These paths are looked up in the position map
to annotate each error with its source location.

Changes:
- SchemaErrors gains a Positions field (parallel to Items)
- New SourcePosition type and JSONSchemaValidateWithPositions function
- buildJSONPositionMap: tokenizes JSON and maps context paths to positions
- buildYAMLPositionMap/walkYAMLNode: walks yaml.v3 Node tree for positions
- Report gains ErrorLines/ErrorColumns (parallel to ValidationErrors)
- SARIF reporter uses per-error positions instead of file-level position
- formatErrors formats schema errors with consistent line/column prefix

Output before:
  error: schema: version: Invalid type. Expected: string, given: integer

Output after:
  error: schema: line 3, column 3: version: Invalid type. Expected: string, given: integer

Author: kehoecj

pkg/cli/cli.go

@@ -164,7 +164,7 @@ func (c *CLI) validate(content []byte, ft filetype.FileType, name, path string)
 		col = ve.Column
 	}
 
-	validationErrors := formatErrors(err, line, col)
+	validationErrors, errLines, errCols := formatErrors(err, line, col)
 	notes := checkJSONCFallback(syntaxErr, ft, content, name)
 
 	return reporter.Report{
@@ -178,6 +178,8 @@ func (c *CLI) validate(content []byte, ft filetype.FileType, name, path string)
 		IsQuiet:          c.quiet,
 		StartLine:        line,
 		StartColumn:      col,
+		ErrorLines:       errLines,
+		ErrorColumns:     errCols,
 	}
 }
 
@@ -195,17 +197,33 @@ func (c *CLI) runSingle(content []byte, ft filetype.FileType, name string) (int,
 	return 0, nil
 }
 
-func formatErrors(err error, line, col int) []string {
+func formatErrors(err error, line, col int) (errs []string, lines []int, cols []int) {
 	if err == nil {
-		return nil
+		return nil, nil, nil
 	}
 	var se *validator.SchemaErrors
 	if errors.As(err, &se) {
 		var errs []string
-		for _, e := range se.Errors() {
-			errs = append(errs, "schema: "+e)
+		var lines, cols []int
+		for i, e := range se.Errors() {
+			var pos validator.SchemaErrorPosition
+			if i < len(se.Positions) {
+				pos = se.Positions[i]
+			}
+			var prefix string
+			switch {
+			case pos.Line > 0 && pos.Column > 0:
+				prefix = fmt.Sprintf("schema: line %d, column %d: ", pos.Line, pos.Column)
+			case pos.Line > 0:
+				prefix = fmt.Sprintf("schema: line %d: ", pos.Line)
+			default:
+				prefix = "schema: "
+			}
+			errs = append(errs, prefix+e)
+			lines = append(lines, pos.Line)
+			cols = append(cols, pos.Column)
 		}
-		return errs
+		return errs, lines, cols
 	}
 
 	msg := err.Error()
@@ -224,7 +242,7 @@ func formatErrors(err error, line, col int) []string {
 		prefix = "syntax: "
 	}
 
-	return []string{prefix + msg}
+	return []string{prefix + msg}, []int{line}, []int{col}
 }
 
 // checkJSONCFallback checks if a failed JSON file is valid JSONC and returns a note if so.

pkg/cli/cli_test.go

@@ -715,6 +715,50 @@ func Test_SchemaErrorsMethod(t *testing.T) {
 	require.Equal(t, "test: error1; error2", se.Error())
 }
 
+func Test_formatErrorsSchemaWithPositions(t *testing.T) {
+	t.Parallel()
+	se := &validator.SchemaErrors{
+		Prefix: "schema validation failed: ",
+		Items:  []string{"port: Invalid type", "name is required"},
+		Positions: []validator.SchemaErrorPosition{
+			{Line: 3, Column: 5},
+			{Line: 0, Column: 0},
+		},
+	}
+	errs, lines, cols := formatErrors(se, 0, 0)
+	require.Len(t, errs, 2)
+	require.Contains(t, errs[0], "line 3, column 5")
+	require.Contains(t, errs[1], "schema: ")
+	require.NotContains(t, errs[1], "line")
+	require.Equal(t, 3, lines[0])
+	require.Equal(t, 0, lines[1])
+	require.Equal(t, 5, cols[0])
+}
+
+func Test_formatErrorsSchemaLineOnly(t *testing.T) {
+	t.Parallel()
+	se := &validator.SchemaErrors{
+		Prefix: "schema validation failed: ",
+		Items:  []string{"port: Invalid type"},
+		Positions: []validator.SchemaErrorPosition{
+			{Line: 7, Column: 0},
+		},
+	}
+	errs, lines, _ := formatErrors(se, 0, 0)
+	require.Len(t, errs, 1)
+	require.Contains(t, errs[0], "line 7:")
+	require.NotContains(t, errs[0], "column")
+	require.Equal(t, 7, lines[0])
+}
+
+func Test_formatErrorsNil(t *testing.T) {
+	t.Parallel()
+	errs, lines, cols := formatErrors(nil, 0, 0)
+	require.Nil(t, errs)
+	require.Nil(t, lines)
+	require.Nil(t, cols)
+}
+
 func Test_CLINoJSONCNoteOnYAML(t *testing.T) {
 	dir := t.TempDir()
 	testhelper.WriteFile(t, dir, "bad.yaml", "a: b\nc: d:::::::::::::::\n")

pkg/reporter/reporter.go

@@ -13,6 +13,8 @@ type Report struct {
 	IsQuiet          bool
 	StartLine        int
 	StartColumn      int
+	ErrorLines       []int
+	ErrorColumns     []int
 }
 
 // Reporter is the interface that wraps the Print method

pkg/reporter/sarif_reporter.go

@@ -106,7 +106,7 @@ func createSARIFReport(reports []Report) (*SARIFLog, error) {
 			continue
 		}
 
-		for _, errMsg := range report.ValidationErrors {
+		for i, errMsg := range report.ValidationErrors {
 			r := result{
 				Kind:    "fail",
 				Level:   "error",
@@ -117,10 +117,17 @@ func createSARIFReport(reports []Report) (*SARIFLog, error) {
 					},
 				}},
 			}
-			if report.StartLine > 0 {
+			errLine, errCol := report.StartLine, report.StartColumn
+			if i < len(report.ErrorLines) && report.ErrorLines[i] > 0 {
+				errLine = report.ErrorLines[i]
+				if i < len(report.ErrorColumns) {
+					errCol = report.ErrorColumns[i]
+				}
+			}
+			if errLine > 0 {
 				r.Locations[0].PhysicalLocation.Region = &region{
-					StartLine:   report.StartLine,
-					StartColumn: report.StartColumn,
+					StartLine:   errLine,
+					StartColumn: errCol,
 				}
 			}
 			runs.Results = append(runs.Results, r)

pkg/validator/json.go

@@ -86,7 +86,8 @@ func (JSONValidator) ValidateSchema(b []byte, filePath string) (bool, error) {
 		return false, err
 	}
 
-	return JSONSchemaValidate(schemaURL, cleanDoc)
+	posMap := buildJSONPositionMap(b)
+	return JSONSchemaValidateWithPositions(schemaURL, cleanDoc, posMap)
 }
 
 // checkJSONDuplicateKeys walks the JSON token stream and reports duplicate keys.
@@ -95,6 +96,107 @@ func checkJSONDuplicateKeys(b []byte) error {
 	return checkDuplicateKeysInDecoder(dec)
 }
 
+// buildJSONPositionMap scans JSON bytes and builds a map from gojsonschema
+// context paths (e.g. "(root).name") to their source position.
+func buildJSONPositionMap(b []byte) map[string]SourcePosition {
+	positions := make(map[string]SourcePosition)
+	dec := json.NewDecoder(strings.NewReader(string(b)))
+
+	offsetToPos := func(offset int64) SourcePosition {
+		if int(offset) > len(b) {
+			offset = int64(len(b))
+		}
+		prefix := b[:offset]
+		line := 1 + strings.Count(string(prefix), "\n")
+		lastNL := strings.LastIndex(string(prefix), "\n")
+		col := int(offset) - lastNL
+		return SourcePosition{Line: line, Column: col}
+	}
+
+	findKeyStart := func(endOffset int64) SourcePosition {
+		for i := int(endOffset) - 1; i >= 0; i-- {
+			if b[i] == '"' {
+				for j := i - 1; j >= 0; j-- {
+					if b[j] == '"' {
+						return offsetToPos(int64(j))
+					}
+				}
+			}
+		}
+		return offsetToPos(endOffset)
+	}
+
+	type frame struct {
+		isArray bool
+		key     string
+	}
+
+	var stack []frame
+	var pendingKey string
+	expectingKey := false
+
+	pathStr := func() string {
+		parts := []string{"(root)"}
+		for _, f := range stack {
+			if f.key != "" {
+				parts = append(parts, f.key)
+			}
+		}
+		if pendingKey != "" {
+			parts = append(parts, pendingKey)
+		}
+		return strings.Join(parts, ".")
+	}
+
+	recordAndReset := func() {
+		pendingKey = ""
+		expectingKey = len(stack) > 0 && !stack[len(stack)-1].isArray
+	}
+
+	for {
+		tok, err := dec.Token()
+		if err != nil {
+			break
+		}
+		afterOffset := dec.InputOffset()
+
+		switch v := tok.(type) {
+		case json.Delim:
+			switch v {
+			case '{':
+				stack = append(stack, frame{isArray: false, key: pendingKey})
+				pendingKey = ""
+				expectingKey = true
+				p := pathStr()
+				if _, exists := positions[p]; !exists {
+					positions[p] = offsetToPos(afterOffset - 1)
+				}
+			case '[':
+				stack = append(stack, frame{isArray: true, key: pendingKey})
+				pendingKey = ""
+			case '}', ']':
+				if len(stack) > 0 {
+					stack = stack[:len(stack)-1]
+				}
+				expectingKey = len(stack) > 0 && !stack[len(stack)-1].isArray
+			default:
+			}
+		case string:
+			if expectingKey && len(stack) > 0 && !stack[len(stack)-1].isArray {
+				pendingKey = v
+				positions[pathStr()] = findKeyStart(afterOffset)
+				expectingKey = false
+			} else {
+				recordAndReset()
+			}
+		default:
+			recordAndReset()
+		}
+	}
+
+	return positions
+}
+
 func checkDuplicateKeysInDecoder(dec *json.Decoder) error {
 	tok, err := dec.Token()
 	if err != nil {

pkg/validator/schema.go

@@ -8,7 +8,24 @@ import (
 	"github.com/xeipuuv/gojsonschema"
 )
 
+// SourcePosition holds a 1-based line and column in the original source file.
+type SourcePosition struct {
+	Line   int
+	Column int
+}
+
 func JSONSchemaValidate(schemaURL string, docJSON []byte) (bool, error) {
+	return validateJSONSchema(schemaURL, docJSON, nil)
+}
+
+// JSONSchemaValidateWithPositions validates docJSON against schemaURL and
+// annotates errors with source positions from posMap. The map keys are
+// gojsonschema context strings like "(root).name".
+func JSONSchemaValidateWithPositions(schemaURL string, docJSON []byte, posMap map[string]SourcePosition) (bool, error) {
+	return validateJSONSchema(schemaURL, docJSON, posMap)
+}
+
+func validateJSONSchema(schemaURL string, docJSON []byte, posMap map[string]SourcePosition) (bool, error) {
 	schemaLoader := gojsonschema.NewReferenceLoader(schemaURL)
 	documentLoader := gojsonschema.NewBytesLoader(docJSON)
 
@@ -19,10 +36,18 @@ func JSONSchemaValidate(schemaURL string, docJSON []byte) (bool, error) {
 
 	if !result.Valid() {
 		var errs []string
+		var positions []SchemaErrorPosition
 		for _, desc := range result.Errors() {
 			errs = append(errs, desc.String())
+			var pos SchemaErrorPosition
+			if posMap != nil {
+				if sp, ok := posMap[desc.Context().String()]; ok {
+					pos = SchemaErrorPosition(sp)
+				}
+			}
+			positions = append(positions, pos)
 		}
-		return false, &SchemaErrors{Prefix: "schema validation failed: ", Items: errs}
+		return false, &SchemaErrors{Prefix: "schema validation failed: ", Items: errs, Positions: positions}
 	}
 
 	return true, nil

pkg/validator/validator.go

@@ -20,12 +20,21 @@ type ValidationError struct {
 func (e *ValidationError) Error() string { return e.Err.Error() }
 func (e *ValidationError) Unwrap() error { return e.Err }
 
+// SchemaErrorPosition holds the source position for a single schema error.
+type SchemaErrorPosition struct {
+	Line   int
+	Column int
+}
+
 // SchemaErrors holds multiple schema validation errors.
 // The joined Error() string is used for backward compatibility,
 // while Errors() returns individual error messages.
+// Positions is parallel to Items — Positions[i] is the source position
+// for Items[i]. A zero-value position means the location is unknown.
 type SchemaErrors struct {
-	Prefix string
-	Items  []string
+	Prefix    string
+	Items     []string
+	Positions []SchemaErrorPosition
 }
 
 func (e *SchemaErrors) Error() string {