openapi3: type the remaining bare-error validation sites (#1187)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: reuvenharrison

.github/docs/openapi3.txt

@@ -45,7 +45,7 @@ func (callback *Callback) Validate(ctx context.Context, opts ...ValidationOption
 		}
 	}
 
-	return validateExtensions(ctx, callback.Extensions)
+	return validateExtensions(ctx, callback.Extensions, callback.Origin)
 }
 
 // UnmarshalJSON sets Callbacks to a copy of data.

openapi3/callback.go

@@ -115,7 +115,7 @@ func (components *Components) Validate(ctx context.Context, opts ...ValidationOp
 	validateMap := func(label string, names []string, validate func(k string) error) error {
 		for _, k := range names {
 			if idErr := ValidateIdentifier(k); idErr != nil {
-				if err := me.emit(fmt.Errorf("%s %q: %w", label, k, idErr)); err != nil {
+				if err := me.emit(&ComponentValidationError{Section: label, Name: k, Cause: idErr}); err != nil {
 					return err
 				}
 				// Skip validating the component's value when its name is
@@ -125,7 +125,7 @@ func (components *Components) Validate(ctx context.Context, opts ...ValidationOp
 				// per component bounded to a single, actionable finding.
 				continue
 			}
-			wrap := func(e error) error { return fmt.Errorf("%s %q: %w", label, k, e) }
+			wrap := func(e error) error { return &ComponentValidationError{Section: label, Name: k, Cause: e} }
 			if err := me.emitWrapped(wrap, validate(k)); err != nil {
 				return err
 			}
@@ -187,7 +187,7 @@ func (components *Components) Validate(ctx context.Context, opts ...ValidationOp
 		return err
 	}
 
-	return me.finalize(validateExtensions(ctx, components.Extensions))
+	return me.finalize(validateExtensions(ctx, components.Extensions, components.Origin))
 }
 
 var _ jsonpointer.JSONPointable = (*Schemas)(nil)

openapi3/components.go

@@ -65,5 +65,5 @@ func (contact *Contact) UnmarshalJSON(data []byte) error {
 func (contact *Contact) Validate(ctx context.Context, opts ...ValidationOption) error {
 	ctx = WithValidationOptions(ctx, opts...)
 
-	return validateExtensions(ctx, contact.Extensions)
+	return validateExtensions(ctx, contact.Extensions, contact.Origin)
 }

openapi3/contact.go

@@ -72,5 +72,5 @@ func (discriminator *Discriminator) UnmarshalJSON(data []byte) error {
 func (discriminator *Discriminator) Validate(ctx context.Context, opts ...ValidationOption) error {
 	ctx = WithValidationOptions(ctx, opts...)
 
-	return validateExtensions(ctx, discriminator.Extensions)
+	return validateExtensions(ctx, discriminator.Extensions, discriminator.Origin)
 }

openapi3/discriminator.go

@@ -3,7 +3,6 @@ package openapi3
 import (
 	"context"
 	"encoding/json"
-	"fmt"
 	"maps"
 )
 
@@ -145,8 +144,8 @@ func (encoding *Encoding) Validate(ctx context.Context, opts ...ValidationOption
 		sm.Style == SerializationPipeDelimited && !sm.Explode,
 		sm.Style == SerializationDeepObject && sm.Explode:
 	default:
-		return fmt.Errorf("serialization method with style=%q and explode=%v is not supported by media type", sm.Style, sm.Explode)
+		return newInvalidSerializationMethod("media type", sm.Style, sm.Explode, encoding.Origin)
 	}
 
-	return validateExtensions(ctx, encoding.Extensions)
+	return validateExtensions(ctx, encoding.Extensions, encoding.Origin)
 }

openapi3/encoding.go

@@ -80,7 +80,7 @@ func (example *Example) Validate(ctx context.Context, opts ...ValidationOption)
 		return newExampleValueOrExternalValueRequired(example.Origin)
 	}
 
-	return validateExtensions(ctx, example.Extensions)
+	return validateExtensions(ctx, example.Extensions, example.Origin)
 }
 
 // UnmarshalJSON sets Examples to a copy of data.

openapi3/example.go

@@ -2,11 +2,17 @@ package openapi3
 
 import (
 	"context"
-	"fmt"
 	"strings"
 )
 
-func validateExtensions(ctx context.Context, extensions map[string]any) error { // FIXME: newtype + Validate(...)
+// validateExtensions reports any non-`x-` keys in the given extensions
+// map that are not explicitly allowed by the validation context. The
+// origin argument is attached to the resulting ExtraSiblingFieldsError
+// so callers can pin the finding to the parent object that carries the
+// unknown keys; pass nil when the parent has no Origin (the loader was
+// run with IncludeOrigin = false, or the parent was constructed
+// programmatically without an Origin set).
+func validateExtensions(ctx context.Context, extensions map[string]any, origin *Origin) error { // FIXME: newtype + Validate(...)
 	allowed := getValidationOptions(ctx).extraSiblingFieldsAllowed
 
 	var unknowns []string
@@ -23,7 +29,7 @@ func validateExtensions(ctx context.Context, extensions map[string]any) error {
 	}
 
 	if len(unknowns) != 0 {
-		return fmt.Errorf("extra sibling fields: %+v", unknowns)
+		return newExtraSiblingFields(unknowns, origin)
 	}
 
 	return nil

openapi3/extension.go

@@ -3,7 +3,6 @@ package openapi3
 import (
 	"context"
 	"encoding/json"
-	"fmt"
 	"maps"
 	"net/url"
 )
@@ -68,10 +67,10 @@ func (e *ExternalDocs) Validate(ctx context.Context, opts ...ValidationOption) e
 		}
 	}
 	if _, err := url.Parse(e.URL); err != nil {
-		if err := me.emit(fmt.Errorf("url is incorrect: %w", err)); err != nil {
+		if err := me.emit(&ExternalDocsURLValidationError{Cause: err}); err != nil {
 			return err
 		}
 	}
 
-	return me.finalize(validateExtensions(ctx, e.Extensions))
+	return me.finalize(validateExtensions(ctx, e.Extensions, e.Origin))
 }

openapi3/external_docs.go

@@ -2,7 +2,6 @@ package openapi3
 
 import (
 	"context"
-	"fmt"
 
 	"github.com/go-openapi/jsonpointer"
 )
@@ -67,28 +66,28 @@ func (header *Header) Validate(ctx context.Context, opts ...ValidationOption) er
 	if smSupported := false ||
 		sm.Style == SerializationSimple && !sm.Explode ||
 		sm.Style == SerializationSimple && sm.Explode; !smSupported {
-		e := fmt.Errorf("serialization method with style=%q and explode=%v is not supported by a header parameter", sm.Style, sm.Explode)
-		return fmt.Errorf("header schema is invalid: %w", e)
+		e := newInvalidSerializationMethod("header", sm.Style, sm.Explode, header.Origin)
+		return &HeaderFieldValidationError{Field: "schema", Cause: e}
 	}
 
 	if (header.Schema == nil) == (len(header.Content) == 0) {
-		return fmt.Errorf("header schema is invalid: %w",
-			newHeaderContentSchemaExactlyOne(header, header.Origin))
+		return &HeaderFieldValidationError{Field: "schema",
+			Cause: newHeaderContentSchemaExactlyOne(header, header.Origin)}
 	}
 	if schema := header.Schema; schema != nil {
 		if err := schema.Validate(ctx); err != nil {
-			return fmt.Errorf("header schema is invalid: %w", err)
+			return &HeaderFieldValidationError{Field: "schema", Cause: err}
 		}
 	}
 
 	if content := header.Content; content != nil {
 		if len(content) > 1 {
-			return fmt.Errorf("header content is invalid: %w",
-				newHeaderContentSingleEntry(header.Origin))
+			return &HeaderFieldValidationError{Field: "content",
+				Cause: newHeaderContentSingleEntry(header.Origin)}
 		}
 
 		if err := content.Validate(ctx); err != nil {
-			return fmt.Errorf("header content is invalid: %w", err)
+			return &HeaderFieldValidationError{Field: "content", Cause: err}
 		}
 	}
 	return nil