Skip to main content

Add descriptions to executable documents | 2025 Update

At a glance​

Timeline​

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:

"""
Request the current status of a time machine and its operator.
"""
query GetTimeMachineStatus(
  "The unique serial number of the time machine to inspect."
  $machineId: ID!

  """
  The year to check the status for.
  **Warning:** certain years may trigger an anomaly in the space-time continuum.
  """
  $year: Int
) {
  timeMachine(id: $machineId) {
    ...TimeMachineDetails
    operator {
        name
        licenseLevel
    }
    status(year: $year)
  }
}

"Time machine details."
fragment TimeMachineDetails on TimeMachine {
  id
  model
  lastMaintenance
}

Implemented in Graphql.js by https://github.com/graphql/graphql-js/pull/4430