Add descriptions to executable documents | 2025 Update

spec/Appendix B -- Grammar Summary.md

@@ -147,9 +147,11 @@ ExecutableDefinition :
 - OperationDefinition
 - FragmentDefinition
 
+Description : StringValue
+
 OperationDefinition :
 
-- OperationType Name? VariablesDefinition? Directives? SelectionSet
+- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet
 - SelectionSet
 
 OperationType : one of `query` `mutation` `subscription`
@@ -174,8 +176,8 @@ FragmentSpread : ... FragmentName Directives?
 
 InlineFragment : ... TypeCondition? Directives? SelectionSet
 
-FragmentDefinition : fragment FragmentName TypeCondition Directives?
-SelectionSet
+FragmentDefinition : Description? fragment FragmentName TypeCondition
+Directives? SelectionSet
 
 FragmentName : Name but not `on`
 
@@ -213,7 +215,8 @@ ObjectField[Const] : Name : Value[?Const]
 
 VariablesDefinition : ( VariableDefinition+ )
 
-VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+VariableDefinition : Description? Variable : Type DefaultValue?
+Directives[Const]?
 
 Variable : $ Name
 
@@ -268,8 +271,6 @@ SchemaExtension :
 
 RootOperationTypeDefinition : OperationType : NamedType
 
-Description : StringValue
-
 TypeDefinition :
 
 - ScalarTypeDefinition

spec/Section 2 -- Language.md

@@ -275,11 +275,74 @@ operations, each operation must be named. When submitting a Document with
 multiple operations to a GraphQL service, the name of the desired operation to
 be executed must also be provided.
 
+## Descriptions
+
+Description : StringValue
+
+Documentation is a first-class feature of GraphQL. GraphQL descriptions are
+defined using the Markdown syntax (as specified by
+[CommonMark](https://commonmark.org/)). Description strings (often
+{BlockString}) occur immediately before the definition they describe.
+
+Descriptions may appear before:
+
+- Operation definitions (queries, mutations, subscriptions) in their full form
+  (not the shorthand form).
+- Fragment definitions.
+- Variable definitions within operation definitions.
+
+Descriptions are not permitted on the shorthand form of operations (e.g.,
+`{ ... }`).
+
+Note: Descriptions and comments in executable GraphQL documents are purely for
+documentation purposes. They MUST NOT affect the execution, validation, or
+response of a GraphQL document. It is safe to remove all descriptions and
+comments from executable documents without changing their behavior or results.
+
+Example:
+
+```graphql example
+"Some description"
+query SomeOperation(
+  "ID you should provide"
+  $id: String
+
+  "Switch for experiment ...."
+  $enableBaz: Boolean = false,
+) {
+  foo(id: $id) {
+    bar
+    baz @include(if: $enableBaz) {
+      ...BazInfo
+    }
+  }
+}
+
+"Some description here"
+fragment BazInfo on Baz {
+  # ...
+}
+```
+
+Counterexample:
+
+```graphql counter-example
+"Descriptions are not permitted on the shorthand form of operations"
+{
+  foo {
+    bar
+    baz {
+      ...BazInfo
+    }
+  }
+}
+```
+
 ## Operations
 
 OperationDefinition :
 
-- OperationType Name? VariablesDefinition? Directives? SelectionSet
+- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet
 - SelectionSet
 
 OperationType : one of `query` `mutation` `subscription`

spec/Section 3 -- Type System.md

@@ -59,6 +59,9 @@ documentation of a GraphQL service remains consistent with its capabilities,
 descriptions of GraphQL definitions are provided alongside their definitions and
 made available via introspection.
 
+Note: See Section 2, "Descriptions", for normative rules and additional details
+on descriptions in executable documents.
+
 To allow GraphQL service designers to easily publish documentation alongside the
 capabilities of a GraphQL service, GraphQL descriptions are defined using the
 Markdown syntax (as specified by [CommonMark](https://commonmark.org/)). In the

spec/Section 6 -- Execution.md

@@ -33,6 +33,12 @@ Note: GraphQL requests do not require any specific serialization format or
 transport mechanism. Message serialization and transport mechanisms should be
 chosen by the implementing service.
 
+Note: Descriptions and comments in executable documents (operation definitions,
+fragment definitions, and variable definitions) MUST be ignored during execution
+and have no effect on the execution, validation, or response of a GraphQL
+document. Descriptions and comments on executable documents MAY be used for
+observability and logging purposes.
+
 ## Executing Requests
 
 To execute a request, the executor must have a parsed {Document} and a selected