Skip to main content

Add descriptions to executable definitions

At a glance

Timeline


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