Updated spec wording for descriptions in executable documents

  - Expanded the "Descriptions" section to clarify that descriptions may appear before operation definitions (full form only), fragment definitions, and variable definitions, but not on the shorthand form of operations.
  - Updated grammar summary and relevant sections to permit descriptions in these locations.
  - Added a normative note that descriptions and comments do not affect execution, validation, or response, and are safe to remove from executable documents.
  - Clarified and consolidated description rules in the type system section, referencing the normative rules in the language section and removing redundant statements.
  - Updated execution section to include a clear normative note about ignoring descriptions and comments during execution.
  - Ensured all changes are cross-referenced and consistent across the specification.

Author: fotoetienne

spec/Appendix B -- Grammar Summary.md

@@ -176,8 +176,8 @@ FragmentSpread : ... FragmentName Directives?
 
 InlineFragment : ... TypeCondition? Directives? SelectionSet
 
-FragmentDefinition : Description? fragment FragmentName TypeCondition Directives?
-SelectionSet
+FragmentDefinition : Description? fragment FragmentName TypeCondition
+Directives? SelectionSet
 
 FragmentName : Name but not `on`
 
@@ -215,7 +215,8 @@ ObjectField[Const] : Name : Value[?Const]
 
 VariablesDefinition : ( VariableDefinition+ )
 
-VariableDefinition : Description? Variable : Type DefaultValue? Directives[Const]?
+VariableDefinition : Description? Variable : Type DefaultValue?
+Directives[Const]?
 
 Variable : $ Name
 

spec/Section 2 -- Language.md

@@ -279,20 +279,70 @@ be executed must also be provided.
 
 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.
+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
+"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 definitions (e.g. queries, fragments, types, fields, arguments, etc.)
-which can be described should provide a {Description} unless they are considered
-self descriptive.
+```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