feat: add description support for OperationDefinition

Implements GraphQL September 2025 spec for operation descriptions.
Operations can now have string or block string descriptions.

Ref: graphql/graphql-spec#1170

Author: asoorm

v2/pkg/ast/ast_operation_definition.go

@@ -34,6 +34,7 @@ func (t OperationType) Name() string {
 }
 
 type OperationDefinition struct {
+	Description            Description        // optional, describes the operation
 	OperationType          OperationType      // one of query, mutation, subscription
 	OperationTypeLiteral   position.Position  // position of the operation type literal, if present
 	Name                   ByteSliceReference // optional, user defined name of the operation
@@ -63,6 +64,14 @@ func (d *Document) OperationDefinitionNameString(ref int) string {
 	return unsafebytes.BytesToString(d.Input.ByteSlice(d.OperationDefinitions[ref].Name))
 }
 
+func (d *Document) OperationDefinitionDescriptionBytes(ref int) ByteSlice {
+	return d.Input.ByteSlice(d.OperationDefinitions[ref].Description.Content)
+}
+
+func (d *Document) OperationDefinitionDescriptionString(ref int) string {
+	return unsafebytes.BytesToString(d.Input.ByteSlice(d.OperationDefinitions[ref].Description.Content))
+}
+
 func (d *Document) AddOperationDefinitionToRootNodes(definition OperationDefinition) Node {
 	d.OperationDefinitions = append(d.OperationDefinitions, definition)
 	node := Node{Kind: NodeKindOperationDefinition, Ref: len(d.OperationDefinitions) - 1}

v2/pkg/astparser/parser.go

@@ -751,8 +751,10 @@ func (p *Parser) parseRootDescription() {
 		p.parseExtension()
 	case identkeyword.SCHEMA:
 		p.parseSchemaDefinition(&description)
+	case identkeyword.QUERY, identkeyword.MUTATION, identkeyword.SUBSCRIPTION:
+		p.parseOperationDefinitionWithDescription(&description)
 	default:
-		p.errUnexpectedIdentKey(p.read(), next, identkeyword.TYPE, identkeyword.INPUT, identkeyword.SCALAR, identkeyword.INTERFACE, identkeyword.UNION, identkeyword.ENUM, identkeyword.DIRECTIVE)
+		p.errUnexpectedIdentKey(p.read(), next, identkeyword.TYPE, identkeyword.INPUT, identkeyword.SCALAR, identkeyword.INTERFACE, identkeyword.UNION, identkeyword.ENUM, identkeyword.DIRECTIVE, identkeyword.QUERY, identkeyword.MUTATION, identkeyword.SUBSCRIPTION)
 	}
 }
 
@@ -1465,9 +1467,17 @@ func (p *Parser) parseTypeCondition() (typeCondition ast.TypeCondition) {
 }
 
 func (p *Parser) parseOperationDefinition() {
+	p.parseOperationDefinitionWithDescription(nil)
+}
+
+func (p *Parser) parseOperationDefinitionWithDescription(description *ast.Description) {
 
 	var operationDefinition ast.OperationDefinition
 
+	if description != nil {
+		operationDefinition.Description = *description
+	}
+
 	next, literal := p.peekLiteral()
 	switch next {
 	case keyword.IDENT:

v2/pkg/astparser/parser_test.go

@@ -1986,6 +1986,122 @@ func TestParser_Parse(t *testing.T) {
 					  role#comment
 					}#comment`, parse, false)
 		})
+
+		t.Run("query with description", func(t *testing.T) {
+			run(`"Fetches a user by ID" query GetUser($id: ID!) { user(id: $id) { id name } }`, parse, false,
+				func(doc *ast.Document, extra interface{}) {
+					query := doc.OperationDefinitions[0]
+					if query.OperationType != ast.OperationTypeQuery {
+						panic("want OperationTypeQuery")
+					}
+					if !query.Description.IsDefined {
+						panic("want description to be defined")
+					}
+					description := doc.Input.ByteSliceString(query.Description.Content)
+					if description != "Fetches a user by ID" {
+						panic(fmt.Errorf("want 'Fetches a user by ID', got '%s'", description))
+					}
+					if doc.Input.ByteSliceString(query.Name) != "GetUser" {
+						panic("want GetUser")
+					}
+				})
+		})
+
+		t.Run("query with block string description", func(t *testing.T) {
+			run(`"""
+Fetches a user by their unique identifier.
+This operation returns detailed user information.
+"""
+query GetUser($id: ID!) { user(id: $id) { id name } }`, parse, false,
+				func(doc *ast.Document, extra interface{}) {
+					query := doc.OperationDefinitions[0]
+					if query.OperationType != ast.OperationTypeQuery {
+						panic("want OperationTypeQuery")
+					}
+					if !query.Description.IsDefined {
+						panic("want description to be defined")
+					}
+					if !query.Description.IsBlockString {
+						panic("want block string description")
+					}
+					description := doc.Input.ByteSliceString(query.Description.Content)
+					expected := "Fetches a user by their unique identifier.\nThis operation returns detailed user information."
+					if description != expected {
+						panic(fmt.Errorf("want '%s', got '%s'", expected, description))
+					}
+				})
+		})
+
+		t.Run("mutation with description", func(t *testing.T) {
+			run(`"Creates a new user" mutation CreateUser($input: UserInput!) { createUser(input: $input) { id } }`, parse, false,
+				func(doc *ast.Document, extra interface{}) {
+					mutation := doc.OperationDefinitions[0]
+					if mutation.OperationType != ast.OperationTypeMutation {
+						panic("want OperationTypeMutation")
+					}
+					if !mutation.Description.IsDefined {
+						panic("want description to be defined")
+					}
+					description := doc.Input.ByteSliceString(mutation.Description.Content)
+					if description != "Creates a new user" {
+						panic(fmt.Errorf("want 'Creates a new user', got '%s'", description))
+					}
+				})
+		})
+
+		t.Run("subscription with description", func(t *testing.T) {
+			run(`"""Subscribes to user updates""" subscription UserUpdated($userId: ID!) { userUpdated(userId: $userId) { id } }`, parse, false,
+				func(doc *ast.Document, extra interface{}) {
+					subscription := doc.OperationDefinitions[0]
+					if subscription.OperationType != ast.OperationTypeSubscription {
+						panic("want OperationTypeSubscription")
+					}
+					if !subscription.Description.IsDefined {
+						panic("want description to be defined")
+					}
+					description := doc.Input.ByteSliceString(subscription.Description.Content)
+					if description != "Subscribes to user updates" {
+						panic(fmt.Errorf("want 'Subscribes to user updates', got '%s'", description))
+					}
+				})
+		})
+
+		t.Run("multiple operations with and without descriptions", func(t *testing.T) {
+			run(`
+"Get user query"
+query GetUser { user { id } }
+
+mutation CreateUser { createUser { id } }
+
+"Subscribe to updates"
+subscription Updates { updates { id } }
+`, parse, false,
+				func(doc *ast.Document, extra interface{}) {
+					// First operation with description
+					query := doc.OperationDefinitions[0]
+					if !query.Description.IsDefined {
+						panic("want first operation description to be defined")
+					}
+					if doc.Input.ByteSliceString(query.Description.Content) != "Get user query" {
+						panic("want 'Get user query'")
+					}
+
+					// Second operation without description
+					mutation := doc.OperationDefinitions[1]
+					if mutation.Description.IsDefined {
+						panic("want second operation description to not be defined")
+					}
+
+					// Third operation with description
+					subscription := doc.OperationDefinitions[2]
+					if !subscription.Description.IsDefined {
+						panic("want third operation description to be defined")
+					}
+					if doc.Input.ByteSliceString(subscription.Description.Content) != "Subscribe to updates" {
+						panic("want 'Subscribe to updates'")
+					}
+				})
+		})
 	})
 	t.Run("variable definition", func(t *testing.T) {
 		t.Run("simple", func(t *testing.T) {

v2/pkg/astparser/testdata/operation_with_description.graphql

@@ -0,0 +1,39 @@
+"""
+Fetches a user by their unique identifier.
+This operation returns detailed user information including profile data.
+"""
+query GetUser($id: ID!) {
+  user(id: $id) {
+    id
+    name
+    email
+  }
+}
+
+"Creates a new user account with the provided information"
+mutation CreateUser($input: UserInput!) {
+  createUser(input: $input) {
+    id
+    name
+  }
+}
+
+"""
+Subscribes to real-time user updates.
+Receives notifications when user data changes.
+"""
+subscription UserUpdated($userId: ID!) {
+  userUpdated(userId: $userId) {
+    id
+    name
+    status
+  }
+}
+
+# Operation without description for backward compatibility
+query GetAllUsers {
+  users {
+    id
+    name
+  }
+}

v2/pkg/astprinter/astprinter.go

@@ -276,6 +276,11 @@ func (p *printVisitor) LeaveArgument(ref int) {
 
 func (p *printVisitor) EnterOperationDefinition(ref int) {
 
+	if p.document.OperationDefinitions[ref].Description.IsDefined {
+		p.must(p.document.PrintDescription(p.document.OperationDefinitions[ref].Description, nil, 0, p.out))
+		p.write(literal.LINETERMINATOR)
+	}
+
 	hasName := p.document.OperationDefinitions[ref].Name.Length() > 0
 	hasVariables := p.document.OperationDefinitions[ref].HasVariableDefinitions