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:

"""
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

[netlify[bot]]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	f2b1b1f63b5a90918b33335c38dabfa406fa995f
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/68642d0cb081ec0008e5192b
😎 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.

[fotoetienne]

1. Section 2.4 was updated, but not 2.9 or 2.11?
2. It might be good to add a sample description to each example?

@glen-84 Good catch, thanks! Updated definitions in 2.9 or 2.11 and also added some descriptions to operation examples throughout section 2

[leebyron]

Almost done!!! Let's get the section 3.2 updated and make this new section more holistic about descriptions - re today's meeting

[fotoetienne]

@leebyron I took another pass. I moved the type system description example from section 3 to section 2, but I could also see an argument for keeping that example where it was. Thoughts?

[leebyron]

This looks really nice @fotoetienne!

I'll do a final editorial pass, but this is an excellent change

[ddevault]

The changelog for the latest edition cites this change as follows:

Descriptions on documents, in motivation for AI-consumers

Nothing in this thread seems to suggest that this is motivated by AI consumers.

[leebyron]

Context for that comes from the discussions during WG meetings where this proposal moved through the approval stages

[fotoetienne]

The changelog for the latest edition cites this change as follows:

Descriptions on documents, in motivation for AI-consumers

Nothing in this thread seems to suggest that this is motivated by AI consumers.

@ddevault My revival of this RFC was motivated by work on a tool (gqai) to spin up MCP servers powered by GraphQL operations. Descriptions are essential for good MCP tools, so having descriptions on operations helps to facilitate that.