Add descriptions to executable definitions

At a glance

• Identifier: #892
• Stage: RFC X / Superseded
• Champion: @IvanGoncharov
• Latest activity: Spec PR closed on 2025-06-26
• Spec PR: https://github.com/graphql/graphql-spec/pull/892

Spec PR description

Was already discussed during WG: https://github.com/graphql/graphql-wg/blob/main/notes/2021-04-01.md#adding-descriptions-to-queries-and-fragments-ivan

I prepare a format proposal, here is a couple of key points:

1. You can add descriptions on operations, fragments, and query variables
2. You can't add description on the short form of operation only full form.

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 {
  # ...
}