Add descriptions to executable documents | 2025 Update (#1170)

* Add descriptions to executable definitions

* 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.

* Add example label to GraphQL code block in Language section

Enables the fancy formatting

* Refactor description section for clarity

Also:
 - add color to operation description example and counter-example
 - add descriptions in operation examples throughout section 2

* Add optional description to fragment and variable definitions

* Prettier

* Refactor time machine status query documentation for clarity and conciseness

* Reduced example

* Single quotes for single line description

Co-authored-by: Glen <glen.84@gmail.com>

* Refactor descriptions text, incorporating feedback from working group

* formatting

* Editorial: move descriptions definition above document

* editorial: move examples back to type system, add some links

* Editorial

---------

Co-authored-by: Ivan Goncharov <ivan.goncharov.ua@gmail.com>
Co-authored-by: Glen <glen.84@gmail.com>
Co-authored-by: Lee Byron <lee@leebyron.com>

Author: 4 people

spec/Appendix B -- Grammar Summary.md

@@ -133,6 +133,8 @@ lines and uniform indentation with {BlockStringValue()}.
 
 ## Document Syntax
 
+Description : StringValue
+
 Document : Definition+
 
 Definition :
@@ -149,7 +151,7 @@ ExecutableDefinition :
 
 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 1 -- Overview.md

@@ -63,10 +63,10 @@ GraphQL has a number of design principles:
   endpoints. A GraphQL response, on the other hand, contains exactly what a
   client asks for and no more.
 
-- **Introspective**: GraphQL is introspective. A GraphQL service's type system
-  can be queryable by the GraphQL language itself, as will be described in this
-  specification. GraphQL introspection serves as a powerful platform for
-  building common tools and client software libraries.
+- **Self-describing**: GraphQL is self-describing and introspective. A GraphQL
+  service's type system can be queryable by the GraphQL language itself, which
+  includes readable documentation. GraphQL introspection serves as a powerful
+  platform for building common developer tools and client software libraries.
 
 Because of these principles, GraphQL is a powerful and productive environment
 for building client applications. Product developers and designers building

spec/Section 2 -- Language.md

@@ -233,6 +233,57 @@ Any {Name} within a GraphQL type system must not start with two underscores
 {"\_\_"} unless it is part of the [introspection system](#sec-Introspection) as
 defined by this specification.
 
+## Descriptions
+
+Description : StringValue
+
+Documentation is a first-class feature of GraphQL by including written
+descriptions on all named definitions in executable {Document} and GraphQL type
+systems, which is also made available via introspection ensuring the
+documentation of a GraphQL service remains consistent with its capabilities (see
+[Type System Descriptions](#sec-Type-System-Descriptions)).
+
+GraphQL descriptions are provided as Markdown (as specified by
+[CommonMark](https://commonmark.org/)). Description strings (often
+{BlockString}) occur immediately before the definition they describe.
+
+This is an example of a well-described operation:
+
+```graphql example
+"""
+Request the current status of a time machine and its operator.
+You can also check the status for a particular year.
+**Warning:** certain years may trigger an anomaly in the space-time continuum.
+"""
+query GetTimeMachineStatus(
+  "The unique serial number of the time machine to inspect."
+  $machineId: ID!
+  "The year to check the status for."
+  $year: Int
+) {
+  timeMachine(id: $machineId) {
+    ...TimeMachineDetails
+    status(year: $year)
+  }
+}
+
+"Details about a time machine and its operator."
+fragment TimeMachineDetails on TimeMachine {
+  id
+  model
+  lastMaintenance
+  operator {
+    name
+    licenseLevel
+  }
+}
+```
+
+Descriptions in GraphQL executable 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.
+
 ## Document
 
 Document : Definition+
@@ -279,7 +330,7 @@ be executed must also be provided.
 
 OperationDefinition :
 
-- OperationType Name? VariablesDefinition? Directives? SelectionSet
+- Description? OperationType Name? VariablesDefinition? Directives? SelectionSet
 - SelectionSet
 
 OperationType : one of `query` `mutation` `subscription`
@@ -298,6 +349,10 @@ For example, this mutation operation might "like" a story and then retrieve the
 new number of likes:
 
 ```graphql example
+"""
+Mark story 12345 as "liked"
+and return the updated number of likes on the story
+"""
 mutation {
   likeStory(storyID: 12345) {
     story {
@@ -322,6 +377,8 @@ For example, this unnamed query operation is written via query shorthand.
 }
 ```
 
+Descriptions are not permitted on query shorthand.
+
 Note: many examples below will use the query short-hand syntax.
 
 ## Selection Sets
@@ -523,8 +580,8 @@ which returns the result:
 
 FragmentSpread : ... FragmentName Directives?
 
-FragmentDefinition : fragment FragmentName TypeCondition Directives?
-SelectionSet
+FragmentDefinition : Description? fragment FragmentName TypeCondition
+Directives? SelectionSet
 
 FragmentName : Name but not `on`
 
@@ -570,6 +627,7 @@ query withFragments {
   }
 }
 
+"Common fields for a user's friends."
 fragment friendFields on User {
   id
   name
@@ -1181,7 +1239,8 @@ Variable : $ Name
 
 VariablesDefinition : ( VariableDefinition+ )
 
-VariableDefinition : Variable : Type DefaultValue? Directives[Const]?
+VariableDefinition : Description? Variable : Type DefaultValue?
+Directives[Const]?
 
 DefaultValue : = Value[Const]
 
@@ -1200,7 +1259,10 @@ In this example, we want to fetch a profile picture size based on the size of a
 particular device:
 
 ```graphql example
-query getZuckProfile($devicePicSize: Int) {
+query getZuckProfile(
+  "The size of the profile picture to fetch."
+  $devicePicSize: Int
+) {
   user(id: 4) {
     id
     name

spec/Section 3 -- Type System.md

@@ -50,20 +50,16 @@ Tools which only seek to produce and extend schema and not execute requests may
 choose to only allow {TypeSystemExtensionDocument} and not allow
 {ExecutableDefinition} but should provide a descriptive error if present.
 
-## Descriptions
+## Type System Descriptions
 
-Description : StringValue
+Documentation is a first-class feature of GraphQL type systems, written
+immediately alongside definitions in a {TypeSystemDocument} and made available
+via introspection.
 
-Documentation is a first-class feature of GraphQL type systems. To ensure the
-documentation of a GraphQL service remains consistent with its capabilities,
-descriptions of GraphQL definitions are provided alongside their definitions and
-made available via introspection.
-
-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
-type system definition language, these description strings (often {BlockString})
-occur immediately before the definition they describe.
+[Descriptions](#sec-Descriptions) allow GraphQL service designers to easily
+provide documentation which remains consistent with the capabilities of a
+GraphQL service. Descriptions provided as Markdown (as specified by
+[CommonMark](https://commonmark.org/)) for every definition in a type system.
 
 GraphQL schema and all other definitions (e.g. types, fields, arguments, etc.)
 which can be described should provide a {Description} unless they are considered

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 observable execution, validation, or response of a
+GraphQL document. Descriptions and comments on executable documents MAY be used
+for non-observable purposes, such as logging and other developer tools.
+
 ## Executing Requests
 
 To execute a request, the executor must have a parsed {Document} and a selected