GraphQL RFC Tracker

RFC X / Superseded

Add descriptions to executable definitions

Opened on2021-10-07
Closed on2025-06-26

At a glance

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

Timeline