Add descriptions to executable documents | 2025 Update
At a glance​
- Identifier: #1170
- Stage: RFC3: Accepted
- Champion: @fotoetienne
- PR: Add descriptions to executable documents | 2025 Update
- Related:
- #892 (Add descriptions to executable definitions)
Timeline​
- 3 commits pushed on 2025-07-01:
- 2 commits pushed on 2025-06-28:
- Added to 2025-06-26 WG agenda
- Commit pushed: Single quotes for single line description on 2025-06-12 by @fotoetienne
- 5 commits pushed on 2025-06-11:
- Spec PR created on 2025-06-05 by fotoetienne
- 2 commits pushed on 2025-06-05:
- Commit pushed: Add descriptions to executable definitions on 2021-10-07 by @IvanGoncharov
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