feat: add Description support for VariableDefinition (September 2025 spec)

v2/pkg/ast/ast_variable_definition.go

@@ -16,8 +16,9 @@ type VariableDefinitionList struct {
 
 // VariableDefinition
 // example:
-// $devicePicSize: Int = 100 @small
+// "The device picture size" $devicePicSize: Int = 100 @small
 type VariableDefinition struct {
+	Description   Description       // optional, describes the variable (September 2025 spec)
 	VariableValue Value             // $ Name
 	Colon         position.Position // :
 	Type          int               // e.g. String
@@ -93,3 +94,14 @@ func (d *Document) VariablePathByArgumentRefAndArgumentPath(argumentRef int, arg
 	// The variable path should be the variable name, e.g., "a", and then the 2nd element from the path onwards
 	return append([]string{string(variableNameBytes)}, argumentPath[1:]...), nil
 }
+
+func (d *Document) VariableDefinitionDescriptionBytes(ref int) ByteSlice {
+	if !d.VariableDefinitions[ref].Description.IsDefined {
+		return nil
+	}
+	return d.Input.ByteSlice(d.VariableDefinitions[ref].Description.Content)
+}
+
+func (d *Document) VariableDefinitionDescriptionString(ref int) string {
+	return unsafebytes.BytesToString(d.VariableDefinitionDescriptionBytes(ref))
+}

v2/pkg/astimport/astimport.go

@@ -162,6 +162,7 @@ func (i *Importer) ImportArguments(refs []int, from, to *ast.Document) []int {
 func (i *Importer) ImportVariableDefinition(ref int, from, to *ast.Document) int {
 
 	variableDefinition := ast.VariableDefinition{
+		Description:   i.ImportDescription(from.VariableDefinitions[ref].Description, from, to),
 		VariableValue: i.ImportValue(from.VariableDefinitions[ref].VariableValue, from, to),
 		Type:          i.ImportType(from.VariableDefinitions[ref].Type, from, to),
 		DefaultValue: ast.DefaultValue{
@@ -182,6 +183,7 @@ func (i *Importer) ImportVariableDefinition(ref int, from, to *ast.Document) int
 func (i *Importer) ImportVariableDefinitionWithRename(ref int, from, to *ast.Document, renameTo string) int {
 
 	variableDefinition := ast.VariableDefinition{
+		Description:   i.ImportDescription(from.VariableDefinitions[ref].Description, from, to),
 		VariableValue: i.ImportValue(from.VariableDefinitions[ref].VariableValue, from, to),
 		Type:          i.ImportTypeWithRename(from.VariableDefinitions[ref].Type, from, to, renameTo),
 		DefaultValue: ast.DefaultValue{
@@ -199,6 +201,14 @@ func (i *Importer) ImportVariableDefinitionWithRename(ref int, from, to *ast.Doc
 	return len(to.VariableDefinitions) - 1
 }
 
+func (i *Importer) ImportDescription(description ast.Description, from, to *ast.Document) ast.Description {
+	if !description.IsDefined {
+		return ast.Description{}
+	}
+	descStr := from.Input.ByteSliceString(description.Content)
+	return to.ImportDescription(descStr)
+}
+
 func (i *Importer) ImportVariableDefinitions(refs []int, from, to *ast.Document) []int {
 	definitions := make([]int, len(refs))
 	for j, k := range refs {

v2/pkg/astimport/astimport_test.go

@@ -318,3 +318,31 @@ func TestImporter_ImportVariableDefinitions(t *testing.T) {
 		[]int{0, 1},
 	))
 }
+
+func TestImportVariableDefinitionWithDescription(t *testing.T) {
+	from, report := astparser.ParseGraphqlDocumentString(`
+		query FindEmployee(
+			"The unique employee identifier"
+			$id: ID!
+		) {
+			employee(id: $id) { id }
+		}
+	`)
+	require.False(t, report.HasErrors())
+
+	to := ast.NewSmallDocument()
+
+	importer := Importer{}
+
+	// Import the variable definition from the source document
+	opDef := from.OperationDefinitions[0]
+	require.Len(t, opDef.VariableDefinitions.Refs, 1)
+
+	srcVarRef := opDef.VariableDefinitions.Refs[0]
+	importedRef := importer.ImportVariableDefinition(srcVarRef, &from, to)
+
+	// Verify the description was preserved
+	importedVar := to.VariableDefinitions[importedRef]
+	assert.True(t, importedVar.Description.IsDefined, "imported variable should have description")
+	assert.Equal(t, "The unique employee identifier", to.Input.ByteSliceString(importedVar.Description.Content))
+}

v2/pkg/astparser/parser.go

@@ -1557,6 +1557,14 @@ func (p *Parser) parseVariableDefinitionList() (list ast.VariableDefinitionList)
 		case keyword.RPAREN:
 			list.RPAREN = p.read().TextPosition
 			return
+		case keyword.STRING, keyword.BLOCKSTRING:
+			// Description before variable definition (September 2025 spec)
+			description := p.parseDescription()
+			if cap(list.Refs) == 0 {
+				list.Refs = p.document.Refs[p.document.NextRefIndex()][:0]
+			}
+			ref := p.parseVariableDefinitionWithDescription(&description)
+			list.Refs = append(list.Refs, ref)
 		case keyword.DOLLAR:
 			if cap(list.Refs) == 0 {
 				list.Refs = p.document.Refs[p.document.NextRefIndex()][:0]
@@ -1567,7 +1575,7 @@ func (p *Parser) parseVariableDefinitionList() (list ast.VariableDefinitionList)
 			}
 			list.Refs = append(list.Refs, ref)
 		default:
-			p.errUnexpectedToken(p.read(), keyword.RPAREN, keyword.DOLLAR)
+			p.errUnexpectedToken(p.read(), keyword.RPAREN, keyword.DOLLAR, keyword.STRING, keyword.BLOCKSTRING)
 			return
 		}
 
@@ -1578,9 +1586,17 @@ func (p *Parser) parseVariableDefinitionList() (list ast.VariableDefinitionList)
 }
 
 func (p *Parser) parseVariableDefinition() int {
+	return p.parseVariableDefinitionWithDescription(nil)
+}
+
+func (p *Parser) parseVariableDefinitionWithDescription(description *ast.Description) int {
 
 	var variableDefinition ast.VariableDefinition
 
+	if description != nil {
+		variableDefinition.Description = *description
+	}
+
 	variableDefinition.VariableValue.Kind = ast.ValueKindVariable
 	variableDefinition.VariableValue.Ref, variableDefinition.VariableValue.Position = p.parseVariableValue()
 

v2/pkg/astparser/parser_test.go

@@ -2986,6 +2986,51 @@ func TestParseFragmentsWithDescriptions(t *testing.T) {
 	assert.False(t, userWithoutDescFrag.Description.IsDefined, "UserWithoutDescription should not have description")
 }
 
+func TestParseVariablesWithDescriptions(t *testing.T) {
+	operationsFile, err := os.ReadFile("./testdata/variable_with_description.graphql")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	doc, report := ParseGraphqlDocumentBytes(operationsFile)
+	if report.HasErrors() {
+		t.Fatal(report)
+	}
+
+	// Verify we parsed both operations
+	require.Len(t, doc.OperationDefinitions, 2)
+
+	// First operation: multi-line with variable descriptions
+	opDef := doc.OperationDefinitions[0]
+	require.True(t, opDef.HasVariableDefinitions)
+	require.Len(t, opDef.VariableDefinitions.Refs, 3)
+
+	// First variable: $id with single-line description
+	var1 := doc.VariableDefinitions[opDef.VariableDefinitions.Refs[0]]
+	assert.True(t, var1.Description.IsDefined, "$id should have description")
+	assert.False(t, var1.Description.IsBlockString, "$id description should be single-line")
+	assert.Equal(t, "The unique employee identifier", doc.Input.ByteSliceString(var1.Description.Content))
+
+	// Second variable: $department with block string description
+	var2 := doc.VariableDefinitions[opDef.VariableDefinitions.Refs[1]]
+	assert.True(t, var2.Description.IsDefined, "$department should have description")
+	assert.True(t, var2.Description.IsBlockString, "$department description should be block string")
+	assert.Contains(t, doc.Input.ByteSliceString(var2.Description.Content), "The department to filter by")
+
+	// Third variable: $limit without description (backward compatibility)
+	var3 := doc.VariableDefinitions[opDef.VariableDefinitions.Refs[2]]
+	assert.False(t, var3.Description.IsDefined, "$limit should not have description")
+
+	// Second operation: single-line with variable description
+	opDef2 := doc.OperationDefinitions[1]
+	require.True(t, opDef2.HasVariableDefinitions)
+	require.Len(t, opDef2.VariableDefinitions.Refs, 1)
+
+	singleLineVar := doc.VariableDefinitions[opDef2.VariableDefinitions.Refs[0]]
+	assert.True(t, singleLineVar.Description.IsDefined, "single-line $id should have description")
+	assert.Equal(t, "The user ID", doc.Input.ByteSliceString(singleLineVar.Description.Content))
+}
+
 func BenchmarkParseStarwars(b *testing.B) {
 
 	inputFileName := "./testdata/starwars.schema.graphql"

v2/pkg/astparser/testdata/variable_with_description.graphql

@@ -0,0 +1,20 @@
+"""
+Get an employee by their ID
+"""
+query FindEmployee(
+  "The unique employee identifier"
+  $id: ID!
+  """
+  The department to filter by.
+  Optional parameter for narrowing results.
+  """
+  $department: String
+  $limit: Int = 10
+) {
+  employee(id: $id) {
+    id
+    name
+  }
+}
+
+query SingleLine("The user ID" $id: ID!) { user(id: $id) { id } }

v2/pkg/astprinter/astprinter.go

@@ -231,6 +231,11 @@ func (p *printVisitor) EnterVariableDefinition(ref int) {
 		p.write(literal.LPAREN)
 	}
 
+	if p.document.VariableDefinitions[ref].Description.IsDefined {
+		p.must(p.document.PrintDescription(p.document.VariableDefinitions[ref].Description, nil, 0, p.out))
+		p.write(literal.SPACE)
+	}
+
 	p.must(p.document.PrintValue(p.document.VariableDefinitions[ref].VariableValue, p.out))
 	p.write(literal.COLON)
 	p.write(literal.SPACE)

v2/pkg/astprinter/astprinter_test.go

@@ -787,6 +787,42 @@ User fields fragment
 """
 fragment UserFields on User {id name}`)
 	})
+	t.Run("variable descriptions", func(t *testing.T) {
+		t.Run("single-line description", func(t *testing.T) {
+			run(t, `query GetUser("The user ID" $id: ID!) {
+	user(id: $id) {
+		id
+	}
+}`, `query GetUser("The user ID" $id: ID!){user(id: $id){id}}`)
+		})
+		t.Run("block string description", func(t *testing.T) {
+			run(t, `query GetUser("""The unique identifier""" $id: ID!) {
+	user(id: $id) {
+		id
+	}
+}`, `query GetUser("""
+The unique identifier
+""" $id: ID!){user(id: $id){id}}`)
+		})
+		t.Run("multiple variables with mixed descriptions", func(t *testing.T) {
+			run(t, `query Search("The search query" $query: String!, $limit: Int) {
+	search(query: $query, limit: $limit) {
+		id
+	}
+}`, `query Search("The search query" $query: String!, $limit: Int){search(query: $query, limit: $limit){id}}`)
+		})
+		t.Run("without description unchanged", func(t *testing.T) {
+			run(t, `query GetUser($id: ID!) {
+	user(id: $id) {
+		id
+	}
+}`, `query GetUser($id: ID!){user(id: $id){id}}`)
+		})
+		t.Run("single-line operation with variable description", func(t *testing.T) {
+			run(t, `query GetUser("The user ID" $id: ID!) { user(id: $id) { id } }`,
+				`query GetUser("The user ID" $id: ID!){user(id: $id){id}}`)
+		})
+	})
 }
 
 func TestPrintArgumentWithBeforeAfterValue(t *testing.T) {

v2/pkg/engine/jsonschema/variables_schema.go

@@ -131,6 +131,17 @@ func (v *VariablesSchemaBuilder) EnterVariableDefinition(ref int) {
 		v.schema.Required = append(v.schema.Required, varName)
 	}
 
+	// Set variable description: use the variable's own description if present (AC2),
+	// otherwise fall back to the field argument description from the schema (AC3)
+	if v.operationDocument.VariableDefinitions[ref].Description.IsDefined {
+		varSchema.Description = v.operationDocument.VariableDefinitionDescriptionString(ref)
+	} else {
+		// Fall back to argument description from schema definition
+		if desc := v.findArgumentDescriptionForVariable(varName); desc != "" {
+			varSchema.Description = desc
+		}
+	}
+
 	// Set default value if exists
 	if v.operationDocument.VariableDefinitionHasDefaultValue(ref) {
 		defaultValue := v.operationDocument.VariableDefinitionDefaultValue(ref)
@@ -150,6 +161,85 @@ func (v *VariablesSchemaBuilder) EnterVariableDefinition(ref int) {
 	v.schema.Properties[varName] = varSchema
 }
 
+// findArgumentDescriptionForVariable looks up the argument description from the schema definition
+// for a variable by matching it to field arguments in the operation's root selection set.
+func (v *VariablesSchemaBuilder) findArgumentDescriptionForVariable(varName string) string {
+	if len(v.operationDocument.OperationDefinitions) == 0 {
+		return ""
+	}
+
+	operationDef := v.operationDocument.OperationDefinitions[0]
+	if !operationDef.HasSelections {
+		return ""
+	}
+
+	// Determine root type name
+	var rootTypeName string
+	switch operationDef.OperationType {
+	case ast.OperationTypeQuery:
+		rootTypeName = "Query"
+	case ast.OperationTypeMutation:
+		rootTypeName = "Mutation"
+	case ast.OperationTypeSubscription:
+		rootTypeName = "Subscription"
+	default:
+		return ""
+	}
+
+	rootType, exists := v.definitionDocument.Index.FirstNodeByNameStr(rootTypeName)
+	if !exists || rootType.Kind != ast.NodeKindObjectTypeDefinition {
+		return ""
+	}
+
+	// Iterate through root fields in the operation's selection set
+	selectionSetRef := operationDef.SelectionSet
+	for _, selectionRef := range v.operationDocument.SelectionSets[selectionSetRef].SelectionRefs {
+		selection := v.operationDocument.Selections[selectionRef]
+		if selection.Kind != ast.SelectionKindField {
+			continue
+		}
+
+		fieldRef := selection.Ref
+		// Check if this field has arguments referencing our variable
+		if !v.operationDocument.FieldHasArguments(fieldRef) {
+			continue
+		}
+
+		for _, argRef := range v.operationDocument.Fields[fieldRef].Arguments.Refs {
+			argValue := v.operationDocument.ArgumentValue(argRef)
+			if argValue.Kind != ast.ValueKindVariable {
+				continue
+			}
+			argVarName := v.operationDocument.VariableValueNameString(argValue.Ref)
+			if argVarName != varName {
+				continue
+			}
+
+			// Found the argument that references this variable.
+			// Look up the corresponding argument definition in the schema.
+			argName := v.operationDocument.ArgumentNameString(argRef)
+			fieldName := v.operationDocument.FieldNameString(fieldRef)
+
+			// Find this field in the root type definition
+			for _, fieldDefRef := range v.definitionDocument.ObjectTypeDefinitions[rootType.Ref].FieldsDefinition.Refs {
+				if v.definitionDocument.FieldDefinitionNameString(fieldDefRef) != fieldName {
+					continue
+				}
+				// Find the argument definition
+				for _, argDefRef := range v.definitionDocument.FieldDefinitionArgumentsDefinitions(fieldDefRef) {
+					if v.definitionDocument.InputValueDefinitionNameString(argDefRef) == argName {
+						if v.definitionDocument.InputValueDefinitions[argDefRef].Description.IsDefined {
+							return v.definitionDocument.InputValueDefinitionDescriptionString(argDefRef)
+						}
+					}
+				}
+			}
+		}
+	}
+
+	return ""
+}
+
 // GetSchema returns the built schema
 func (v *VariablesSchemaBuilder) GetSchema() *JsonSchema {
 	// If we have required fields, the root schema cannot be nullable