Merge pull request #756 from graph-gophers/validate-deprecated

feat: validate deprecated fields

Author: pavelnikolov

CHANGELOG.md

@@ -1,5 +1,7 @@
 # CHANGELOG
 
+* [FEATURE] Add `ValidateDeprecated()` schema option to enable validation of deprecated fields, arguments (including directive arguments), input fields, and enum values in queries. When enabled, usage of deprecated schema elements results in validation errors. This opt-in approach allows applications to enforce deprecation policies without breaking existing clients.
+
 * [FEATURE] Support executable-document description strings on full-form operations, fragments, and variable definitions. Descriptions remain non-semantic and do not change validation or execution behavior. Executable `#` comments remain ignored.
 
 [v1.9.0](https://github.com/graph-gophers/graphql-go/releases/tag/v1.9.0) Release v1.9.0

example_deprecated_test.go

@@ -0,0 +1,43 @@
+package graphql_test
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+
+	graphql "github.com/graph-gophers/graphql-go"
+)
+
+type testValidateDeprecatedResolver struct{}
+
+func (r *testValidateDeprecatedResolver) DeprecatedField() string {
+	return "old value"
+}
+
+func Example_validateDeprecated() {
+	const sdl = `
+		schema {
+			query: Query
+		}
+		type Query {
+			deprecatedField: String! @deprecated(reason: "Use replacementField")
+		}
+	`
+
+	schema := graphql.MustParseSchema(sdl, &testValidateDeprecatedResolver{})
+	res := schema.Exec(context.Background(), `{ deprecatedField }`, "", nil)
+	fmt.Println("Without validation:")
+	_ = json.NewEncoder(os.Stdout).Encode(res)
+
+	clone := schema.MustClone(&testValidateDeprecatedResolver{}, graphql.ValidateDeprecated())
+	res = clone.Exec(context.Background(), `{ deprecatedField }`, "", nil)
+	fmt.Println("With validation:")
+	_ = json.NewEncoder(os.Stdout).Encode(res)
+
+	// Output:
+	// Without validation:
+	// {"data":{"deprecatedField":"old value"}}
+	// With validation:
+	// {"errors":[{"message":"The field Query.deprecatedField is deprecated. Use replacementField","locations":[{"line":1,"column":3}]}]}
+}

graphql.go

@@ -194,6 +194,7 @@ type Schema struct {
 	disableMemoryPooling     bool
 	maxPooledBufferCapacity  int
 	overlapPairLimit         int
+	validateDeprecated       bool
 }
 
 // AST returns the abstract syntax tree of the GraphQL schema definition.
@@ -284,6 +285,14 @@ func OverlapValidationLimit(n int) SchemaOpt {
 	return func(s *Schema) { s.overlapPairLimit = n }
 }
 
+// ValidateDeprecated enables validation errors when a query uses deprecated fields, arguments,
+// enum values, or input fields (rule: NoDeprecatedCustomRule). By default, querying deprecated
+// schema elements is allowed and produces no errors, matching the behaviour of the graphql-js
+// reference implementation where NoDeprecatedCustomRule is an opt-in custom rule.
+func ValidateDeprecated() SchemaOpt {
+	return func(s *Schema) { s.validateDeprecated = true }
+}
+
 // Tracer is used to trace queries and fields. It defaults to [noop.Tracer].
 func Tracer(t tracer.Tracer) SchemaOpt {
 	return func(s *Schema) {
@@ -379,7 +388,7 @@ func (s *Schema) ValidateWithVariables(queryString string, variables map[string]
 		return []*errors.QueryError{errors.Errorf("executable document must contain at least one operation")}
 	}
 
-	return validation.Validate(s.schema, doc, variables, s.maxDepth, s.overlapPairLimit)
+	return validation.Validate(s.schema, doc, variables, s.maxDepth, s.overlapPairLimit, s.validateDeprecated)
 }
 
 // Exec executes the given query with the schema's resolver. It panics if the schema was created
@@ -402,7 +411,7 @@ func (s *Schema) exec(ctx context.Context, queryString string, operationName str
 	}
 
 	validationFinish := s.validationTracer.TraceValidation(ctx)
-	errs := validation.Validate(s.schema, doc, variables, s.maxDepth, s.overlapPairLimit)
+	errs := validation.Validate(s.schema, doc, variables, s.maxDepth, s.overlapPairLimit, s.validateDeprecated)
 	validationFinish(errs)
 	if len(errs) != 0 {
 		return &Response{Errors: errs}

internal/validation/overlap_fuzz_test.go

@@ -71,7 +71,7 @@ func FuzzValidateOverlapMixed(f *testing.F) {
 			return
 		}
 		// Use overlap limit to bound cost.
-		errs := v.Validate(s, doc, nil, 0, 10_000)
+		errs := v.Validate(s, doc, nil, 0, 10_000, false)
 		// Ensure no panic (implicit). Optionally sanity check: errors slice must not be ridiculously huge.
 		if len(errs) > 1000 {
 			t.Fatalf("too many errors: %d", len(errs))

internal/validation/validate_max_depth_test.go

@@ -83,7 +83,7 @@ func (tc maxDepthTestCase) Run(t *testing.T, s *ast.Schema) {
 			t.Fatal(qErr)
 		}
 
-		errs := Validate(s, doc, nil, tc.depth, 0)
+		errs := Validate(s, doc, nil, tc.depth, 0, false)
 		if len(tc.expectedErrors) > 0 {
 			if len(errs) > 0 {
 				for _, expected := range tc.expectedErrors {
@@ -489,7 +489,7 @@ func TestMaxDepthValidation(t *testing.T) {
 				t.Fatal(err)
 			}
 
-			context := newContext(s, doc, tc.maxDepth, 0)
+			context := newContext(s, doc, tc.maxDepth, 0, false)
 			op := doc.Operations[0]
 
 			opc := &opContext{context: context, ops: doc.Operations}

internal/validation/validation.go

@@ -43,6 +43,7 @@ type context struct {
 	overlapPairLimit     int
 	overlapPairsObserved int
 	overlapLimitHit      bool
+	validateDeprecated   bool
 }
 
 func (c *context) addErr(loc errors.Location, rule string, format string, a ...any) {
@@ -62,21 +63,22 @@ type opContext struct {
 	ops []*ast.OperationDefinition
 }
 
-func newContext(s *ast.Schema, doc *ast.ExecutableDefinition, maxDepth int, overlapPairLimit int) *context {
+func newContext(s *ast.Schema, doc *ast.ExecutableDefinition, maxDepth int, overlapPairLimit int, validateDeprecated bool) *context {
 	return &context{
-		schema:           s,
-		doc:              doc,
-		opErrs:           make(map[*ast.OperationDefinition][]*errors.QueryError),
-		usedVars:         make(map[*ast.OperationDefinition]varSet),
-		fieldMap:         make(map[*ast.Field]fieldInfo),
-		overlapValidated: make(map[selectionPair]bool),
-		maxDepth:         maxDepth,
-		overlapPairLimit: overlapPairLimit,
+		schema:             s,
+		doc:                doc,
+		opErrs:             make(map[*ast.OperationDefinition][]*errors.QueryError),
+		usedVars:           make(map[*ast.OperationDefinition]varSet),
+		fieldMap:           make(map[*ast.Field]fieldInfo),
+		overlapValidated:   make(map[selectionPair]bool),
+		maxDepth:           maxDepth,
+		overlapPairLimit:   overlapPairLimit,
+		validateDeprecated: validateDeprecated,
 	}
 }
 
-func Validate(s *ast.Schema, doc *ast.ExecutableDefinition, variables map[string]any, maxDepth int, overlapPairLimit int) []*errors.QueryError {
-	c := newContext(s, doc, maxDepth, overlapPairLimit)
+func Validate(s *ast.Schema, doc *ast.ExecutableDefinition, variables map[string]any, maxDepth int, overlapPairLimit int, validateDeprecated bool) []*errors.QueryError {
+	c := newContext(s, doc, maxDepth, overlapPairLimit, validateDeprecated)
 
 	opNames := make(nameSet, len(doc.Operations))
 	fragUsedBy := make(map[*ast.FragmentDefinition][]*ast.OperationDefinition)
@@ -628,8 +630,10 @@ func validateSelection(c *opContext, sel ast.Selection, t ast.NamedType) {
 
 		validateArgumentLiterals(c, sel.Arguments)
 		if f != nil {
-			if reason, ok := deprecatedReason(f.Directives); ok && t != nil {
-				c.addErr(sel.Name.Loc, "NoDeprecatedCustomRule", "The field %s.%s is deprecated. %s", t.TypeName(), fieldName, reason)
+			if c.validateDeprecated {
+				if reason, ok := deprecatedReason(f.Directives); ok && t != nil {
+					c.addErr(sel.Name.Loc, "NoDeprecatedCustomRule", "The field %s.%s is deprecated. %s", t.TypeName(), fieldName, reason)
+				}
 			}
 
 			validateArgumentTypes(c, sel.Arguments, f.Arguments, sel.Alias.Loc,
@@ -643,8 +647,10 @@ func validateSelection(c *opContext, sel ast.Selection, t ast.NamedType) {
 					if argDecl == nil {
 						continue
 					}
-					if reason, ok := deprecatedReason(argDecl.Directives); ok {
-						c.addErr(selArg.Name.Loc, "NoDeprecatedCustomRule", "Field %q argument %q is deprecated. %s", t.TypeName()+"."+fieldName, selArg.Name.Name, reason)
+					if c.validateDeprecated {
+						if reason, ok := deprecatedReason(argDecl.Directives); ok {
+							c.addErr(selArg.Name.Loc, "NoDeprecatedCustomRule", "Field %q argument %q is deprecated. %s", t.TypeName()+"."+fieldName, selArg.Name.Name, reason)
+						}
 					}
 				}
 
@@ -658,8 +664,10 @@ func validateSelection(c *opContext, sel ast.Selection, t ast.NamedType) {
 						if argDecl == nil {
 							continue
 						}
-						if reason, ok := deprecatedReason(argDecl.Directives); ok {
-							c.addErr(selArg.Name.Loc, "NoDeprecatedCustomRule", "Directive %q argument %q is deprecated. %s", "@"+directive.Name.Name, selArg.Name.Name, reason)
+						if c.validateDeprecated {
+							if reason, ok := deprecatedReason(argDecl.Directives); ok {
+								c.addErr(selArg.Name.Loc, "NoDeprecatedCustomRule", "Directive %q argument %q is deprecated. %s", "@"+directive.Name.Name, selArg.Name.Name, reason)
+							}
 						}
 					}
 				}
@@ -1078,8 +1086,10 @@ func validateDirectives(c *opContext, loc string, directives ast.DirectiveList)
 				if argDecl == nil {
 					continue
 				}
-				if reason, ok := deprecatedReason(argDecl.Directives); ok {
-					c.addErr(selArg.Name.Loc, "NoDeprecatedCustomRule", "Directive %q argument %q is deprecated. %s", "@"+dirName, selArg.Name.Name, reason)
+				if c.validateDeprecated {
+					if reason, ok := deprecatedReason(argDecl.Directives); ok {
+						c.addErr(selArg.Name.Loc, "NoDeprecatedCustomRule", "Directive %q argument %q is deprecated. %s", "@"+dirName, selArg.Name.Name, reason)
+					}
 				}
 			}
 		}
@@ -1267,8 +1277,10 @@ func validateValueType(c *opContext, v ast.Value, t ast.Type) (bool, errors.Loca
 			if option.EnumValue != lit.Text {
 				continue
 			}
-			if depReason, deprecated := deprecatedReason(option.Directives); deprecated {
-				c.addErr(lit.Location(), "NoDeprecatedCustomRule", "The enum value %q is deprecated. %s", enumType.Name+"."+option.EnumValue, depReason)
+			if c.validateDeprecated {
+				if depReason, deprecated := deprecatedReason(option.Directives); deprecated {
+					c.addErr(lit.Location(), "NoDeprecatedCustomRule", "The enum value %q is deprecated. %s", enumType.Name+"."+option.EnumValue, depReason)
+				}
 			}
 			break
 		}
@@ -1302,7 +1314,7 @@ func validateValueType(c *opContext, v ast.Value, t ast.Type) (bool, errors.Loca
 				suggestion := makeSuggestion("Did you mean", t.Values.Names(), name)
 				return false, f.Name.Loc, fmt.Sprintf("Field %q is not defined by type %q.%s", name, t.Name, suggestion)
 			}
-			if depReason, deprecated := deprecatedReason(iv.Directives); deprecated {
+			if depReason, deprecated := deprecatedReason(iv.Directives); deprecated && c.validateDeprecated {
 				c.addErr(f.Name.Loc, "NoDeprecatedCustomRule", "The input field %s.%s is deprecated. %s", t.Name, iv.Name.Name, depReason)
 			}
 			if ok, errLoc, reason := validateValueType(c, f.Value, iv.Type); !ok {

internal/validation/validation_bench_test.go

@@ -65,7 +65,7 @@ func BenchmarkValidate(b *testing.B) {
 		b.Run(tc.name, func(b *testing.B) {
 			b.ReportAllocs()
 			for b.Loop() {
-				benchErrs = validation.Validate(s, doc, nil, 0, 0)
+				benchErrs = validation.Validate(s, doc, nil, 0, 0, false)
 			}
 		})
 	}
@@ -91,7 +91,7 @@ func BenchmarkValidateWorstCaseAliasCollision(b *testing.B) {
 		b.Run("alias-collision-"+strconv.Itoa(n), func(b *testing.B) {
 			b.ReportAllocs()
 			for b.Loop() {
-				benchErrs = validation.Validate(s, doc, nil, 0, 0)
+				benchErrs = validation.Validate(s, doc, nil, 0, 0, false)
 			}
 
 			if b.N > 0 && expectedPairs > 0 {

internal/validation/validation_test.go

@@ -82,7 +82,7 @@ func TestValidate(t *testing.T) {
 			if err != nil {
 				t.Fatalf("failed to parse query: %s", err)
 			}
-			errs := validation.Validate(schemas[test.Schema], d, test.Vars, 0, 0)
+			errs := validation.Validate(schemas[test.Schema], d, test.Vars, 0, 0, test.Rule == "NoDeprecatedCustomRule")
 			got := []*errors.QueryError{}
 			for _, err := range errs {
 				if err.Rule == test.Rule {

subscriptions.go

@@ -40,7 +40,7 @@ func (s *Schema) subscribe(ctx context.Context, queryString string, operationNam
 	}
 
 	validationFinish := s.validationTracer.TraceValidation(ctx)
-	errs := validation.Validate(s.schema, doc, variables, s.maxDepth, s.overlapPairLimit)
+	errs := validation.Validate(s.schema, doc, variables, s.maxDepth, s.overlapPairLimit, s.validateDeprecated)
 	validationFinish(errs)
 	if len(errs) != 0 {
 		return sendAndReturnClosed(&Response{Errors: errs})