Add descriptions to executable documents | 2025 Update

[fotoetienne]

This PR builds upon @IvanGoncharov's 2021 RFC, with changes rebased onto the current spec and updated to incorporate feedback from previous discussion as well as an additional editorial pass.

Descriptions are a core feature of GraphQL, enabling schema and document authors to provide human-readable documentation directly alongside type system elements and executable definitions. This proposal extends the utility of descriptions by allowing them to appear not only on type system definitions, but also on operations, fragments, and variable definitions within executable documents.

Enabling descriptions in these locations improves the expressiveness and maintainability of GraphQL documents, supports better tooling and code generation, and enhances the developer experience by making intent and usage clearer at the point of definition. Importantly, descriptions remain non-semantic—they do not affect execution, validation, or response—ensuring that they serve purely as documentation and can be safely removed without impacting behavior. This change aligns with GraphQL’s commitment to self-documenting APIs and empowers teams to deliver more understandable and maintainable GraphQL applications.

Key points:

• You can add descriptions on operations, fragments, and query variables
• You can't add description on the the shorthand form of operations, only the full form
• Descriptions on operations do not affect query execution, validation, or response

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

Implemented in Graphql.js by graphql/graphql-js#4430

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	1a1a4b3
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/6842212b910552000851e0c0
😎 Deploy Preview	https://deploy-preview-1170--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[JoviDeCroock]

What's the use case for providing descriptions for a FragmentDefinition. Is this tailored to the case where we use a FragmentDefinition as a reusable selection-set across the codebase? Do we really want to encourage that? I'd think that with Fragment Arguments this could carry merit though

[martinbonnin]

We have it in Apollo Kotlin to add Kdoc to the generated models. Not 100% sure how many people use it. Probably not too many but I would still include it for consistency.

We have also APIs to load fragments from the cache so maybe having more contextual info about what is loaded could help.

[martinbonnin]

I'm not sure where we stand on adding new syntax in the spec. I know we have this:

  Once a query is written, it should always mean the same thing and return the
  same shaped result. Future changes should not change the meaning of existing
  schema or requests or in any other way cause an existing compliant GraphQL
  service to become non-compliant for prior versions of the spec.

This change would be fine in that regard I think: all existing documents are still working exactly as before.

This may still cause interoperability issues: an old version of GraphiQL will show an error on the description.

This is probably okay but do we have examples of how we handled that in the past?

Do we need to make this dependent on service capabilities?