feat(openapi3): ForbiddenFieldError cluster for set-but-not-allowed fields

Converts four 'field MUST NOT be set in this context' sites:
- header.name (given by the headers map key)
- header.in (implicitly 'header')
- OAuth flow authorizationUrl (wrong flow type)
- OAuth flow tokenUrl (wrong flow type)

Author: reuvenharrison

.github/docs/openapi3.txt

@@ -727,6 +727,24 @@ func (e *FieldVersionMismatchError) Error() string
 
 func (e *FieldVersionMismatchError) Unwrap() error
 
+type ForbiddenFieldError struct {
+	// Field is the name of the forbidden field (e.g. "name", "in",
+	// "authorizationUrl", "tokenUrl").
+	Field string
+	// Cause is the underlying leaf error. Walked by errors.Unwrap.
+	Cause error
+	// Origin is the source location of the offending element when the
+	// document was loaded with Loader.IncludeOrigin = true.
+	Origin *Origin
+}
+    ForbiddenFieldError clusters "field X must not be set in this context"
+    failures (header.name and header.in inside a Headers map, OAuth flow URLs
+    that don't apply to the chosen flow type).
+
+func (e *ForbiddenFieldError) Error() string
+
+func (e *ForbiddenFieldError) Unwrap() error
+
 type FormatValidator[T any] interface {
 	Validate(value T) error
 }
@@ -769,6 +787,14 @@ func (header *Header) UnmarshalJSON(data []byte) error
 func (header *Header) Validate(ctx context.Context, opts ...ValidationOption) error
     Validate returns an error if Header does not comply with the OpenAPI spec.
 
+type HeaderInForbidden struct{ ValidationError }
+
+func (e *HeaderInForbidden) As(target any) bool
+
+type HeaderNameForbidden struct{ ValidationError }
+
+func (e *HeaderNameForbidden) As(target any) bool
+
 type HeaderRef struct {
 	// Extensions only captures fields starting with 'x-' as no other fields
 	// are allowed by the openapi spec.
@@ -1165,6 +1191,14 @@ func (flow *OAuthFlow) Validate(ctx context.Context, opts ...ValidationOption) e
     Validate returns an error if OAuthFlows does not comply with the OpenAPI
     spec.
 
+type OAuthFlowAuthorizationURLForbidden struct{ ValidationError }
+
+func (e *OAuthFlowAuthorizationURLForbidden) As(target any) bool
+
+type OAuthFlowTokenURLForbidden struct{ ValidationError }
+
+func (e *OAuthFlowTokenURLForbidden) As(target any) bool
+
 type OAuthFlows struct {
 	Extensions map[string]any `json:"-" yaml:"-"`
 	Origin     *Origin        `json:"-" yaml:"-"`

openapi3/header.go

@@ -54,10 +54,10 @@ func (header *Header) Validate(ctx context.Context, opts ...ValidationOption) er
 	ctx = WithValidationOptions(ctx, opts...)
 
 	if header.Name != "" {
-		return errors.New("header 'name' MUST NOT be specified, it is given in the corresponding headers map")
+		return newHeaderNameForbidden(header.Origin)
 	}
 	if header.In != "" {
-		return errors.New("header 'in' MUST NOT be specified, it is implicitly in header")
+		return newHeaderInForbidden(header.Origin)
 	}
 
 	// Validate a parameter's serialization method.

openapi3/security_scheme.go

@@ -404,7 +404,7 @@ func (flow *OAuthFlow) validate(ctx context.Context, typ oAuthFlowType, opts ...
 		case flow.AuthorizationURL == "" && in:
 			return errors.New("field 'authorizationUrl' is empty or missing")
 		case flow.AuthorizationURL != "" && !in:
-			return errors.New("field 'authorizationUrl' should not be set")
+			return newOAuthFlowAuthorizationURLForbidden(flow.Origin)
 		case flow.AuthorizationURL != "":
 			if _, err := url.Parse(flow.AuthorizationURL); err != nil {
 				return fmt.Errorf("field 'authorizationUrl' is invalid: %w", err)
@@ -417,7 +417,7 @@ func (flow *OAuthFlow) validate(ctx context.Context, typ oAuthFlowType, opts ...
 		case flow.TokenURL == "" && in:
 			return errors.New("field 'tokenUrl' is empty or missing")
 		case flow.TokenURL != "" && !in:
-			return errors.New("field 'tokenUrl' should not be set")
+			return newOAuthFlowTokenURLForbidden(flow.Origin)
 		case flow.TokenURL != "":
 			if _, err := url.Parse(flow.TokenURL); err != nil {
 				return fmt.Errorf("field 'tokenUrl' is invalid: %w", err)

openapi3/validation_error.go

@@ -155,6 +155,23 @@ type FieldVersionMismatchError struct {
 func (e *FieldVersionMismatchError) Error() string { return e.Cause.Error() }
 func (e *FieldVersionMismatchError) Unwrap() error { return e.Cause }
 
+// ForbiddenFieldError clusters "field X must not be set in this
+// context" failures (header.name and header.in inside a Headers map,
+// OAuth flow URLs that don't apply to the chosen flow type).
+type ForbiddenFieldError struct {
+	// Field is the name of the forbidden field (e.g. "name", "in",
+	// "authorizationUrl", "tokenUrl").
+	Field string
+	// Cause is the underlying leaf error. Walked by errors.Unwrap.
+	Cause error
+	// Origin is the source location of the offending element when the
+	// document was loaded with Loader.IncludeOrigin = true.
+	Origin *Origin
+}
+
+func (e *ForbiddenFieldError) Error() string { return e.Cause.Error() }
+func (e *ForbiddenFieldError) Unwrap() error { return e.Cause }
+
 // ---------------------------------------------------------------------
 // Leaf types — one per call site. Each embeds ValidationError for
 // Error() and As-to-base, and is wrapped in its cluster type when
@@ -198,6 +215,32 @@ func (e *ServerURLRequired) As(target any) bool {
 	return asValidationError(target, &e.ValidationError)
 }
 
+// ForbiddenFieldError leaves.
+
+type HeaderNameForbidden struct{ ValidationError }
+
+func (e *HeaderNameForbidden) As(target any) bool {
+	return asValidationError(target, &e.ValidationError)
+}
+
+type HeaderInForbidden struct{ ValidationError }
+
+func (e *HeaderInForbidden) As(target any) bool {
+	return asValidationError(target, &e.ValidationError)
+}
+
+type OAuthFlowAuthorizationURLForbidden struct{ ValidationError }
+
+func (e *OAuthFlowAuthorizationURLForbidden) As(target any) bool {
+	return asValidationError(target, &e.ValidationError)
+}
+
+type OAuthFlowTokenURLForbidden struct{ ValidationError }
+
+func (e *OAuthFlowTokenURLForbidden) As(target any) bool {
+	return asValidationError(target, &e.ValidationError)
+}
+
 // FieldVersionMismatchError leaves — non-schema fields.
 
 type InfoSummaryFieldFor31Plus struct{ ValidationError }
@@ -414,6 +457,36 @@ func newServerURLRequired(origin *Origin) error {
 		&ServerURLRequired{ValidationError{Message: "value of url must be a non-empty string"}}, origin)
 }
 
+// newForbiddenField wraps leaf in a *ForbiddenFieldError carrying the
+// name of the field that the spec forbids in the current context.
+func newForbiddenField(field string, leaf error, origin *Origin) error {
+	return &ForbiddenFieldError{Field: field, Cause: leaf, Origin: origin}
+}
+
+func newHeaderNameForbidden(origin *Origin) error {
+	const msg = "header 'name' MUST NOT be specified, it is given in the corresponding headers map"
+	return newForbiddenField("name",
+		&HeaderNameForbidden{ValidationError{Message: msg}}, origin)
+}
+
+func newHeaderInForbidden(origin *Origin) error {
+	const msg = "header 'in' MUST NOT be specified, it is implicitly in header"
+	return newForbiddenField("in",
+		&HeaderInForbidden{ValidationError{Message: msg}}, origin)
+}
+
+func newOAuthFlowAuthorizationURLForbidden(origin *Origin) error {
+	const msg = "field 'authorizationUrl' should not be set"
+	return newForbiddenField("authorizationUrl",
+		&OAuthFlowAuthorizationURLForbidden{ValidationError{Message: msg}}, origin)
+}
+
+func newOAuthFlowTokenURLForbidden(origin *Origin) error {
+	const msg = "field 'tokenUrl' should not be set"
+	return newForbiddenField("tokenUrl",
+		&OAuthFlowTokenURLForbidden{ValidationError{Message: msg}}, origin)
+}
+
 // newSchemaValueError wraps the result of schema.VisitJSON in a
 // *SchemaValueError cluster, identifying which schema sub-field
 // (example, default, ...) carried the offending value. cause is

openapi3/validation_error_test.go

@@ -429,3 +429,38 @@ func TestValidationError_FlowsThroughMultiError(t *testing.T) {
 	var ve *openapi3.ValidationError
 	require.True(t, errors.As(me, &ve))
 }
+
+// Pin ForbiddenFieldError cluster + leaf reachability for the four
+// sites where a field is set but the spec forbids it in that context.
+func TestValidationError_ForbiddenFieldLeaves(t *testing.T) {
+	t.Run("header.name forbidden", func(t *testing.T) {
+		h := &openapi3.Header{Parameter: openapi3.Parameter{Name: "X-Trace"}}
+		err := h.Validate(context.Background())
+		require.EqualError(t, err,
+			"header 'name' MUST NOT be specified, it is given in the corresponding headers map")
+
+		var ffe *openapi3.ForbiddenFieldError
+		require.True(t, errors.As(err, &ffe))
+		require.Equal(t, "name", ffe.Field)
+
+		var leaf *openapi3.HeaderNameForbidden
+		require.True(t, errors.As(err, &leaf))
+
+		var ve *openapi3.ValidationError
+		require.True(t, errors.As(err, &ve))
+	})
+
+	t.Run("header.in forbidden", func(t *testing.T) {
+		h := &openapi3.Header{Parameter: openapi3.Parameter{In: "header"}}
+		err := h.Validate(context.Background())
+		require.EqualError(t, err,
+			"header 'in' MUST NOT be specified, it is implicitly in header")
+
+		var ffe *openapi3.ForbiddenFieldError
+		require.True(t, errors.As(err, &ffe))
+		require.Equal(t, "in", ffe.Field)
+
+		var leaf *openapi3.HeaderInForbidden
+		require.True(t, errors.As(err, &leaf))
+	})
+}