GraphQL spec September 2025

[tyranron]

September 2025 version of GraphQL spec has been released.

Changelog

Notable contributions

A few notable changes in this edition:

• OneOf input objects, aka "input unions" (graphql/graphql-spec#825)
• Schema coordinates as a standard for GraphQL tooling and reporting (graphql/graphql-spec#794)
• Descriptions on documents, in motivation for AI-consumers (graphql/graphql-spec#1170)
• Broader support for deprecation across a GraphQL Schema (graphql/graphql-spec#805 graphql/graphql-spec#1040 graphql-spec#1053 graphql/graphql-spec#1142)
• GraphQL language has been updated to support the full Unicode range (graphql/graphql-spec#849)
• Countless editorial improvements! The spec is much easier to read and contribute to, with fewer ambiguities.

Roadmap

• [x] Support @oneOf input objects
  • #1354
  • #1062
  • #1055
  • graphql/graphql-spec#825
• [x] Support full unicode range
  • #1349
  • graphql/graphql-spec#849
  • graphql/graphql-spec#687
• [x] Support @deprecated on input values
  • #1348
  • #864
  • graphql/graphql-spec#805
• [x] Make @deprecated(reason: ...) non-Null
  • #1348
  • graphql/graphql-spec#1040
• [ ] Reject deprecated fields when interface field is not deprecated
  • graphql/graphql-spec#1053
• [x] Make includeDeprecated field in introspection non-Null
  • #1348
  • graphql/graphql-spec#1142
• [x] Support description on documents
  • #1349
  • graphql/graphql-spec#1170
• [x] ~~Allow specifying schema description~~ (already possible)
  • #1349
  • graphql/graphql-spec#1167
• [x] Rename VariableDefinitions to VariablesDefinition
  • #1353
  • graphql/graphql-spec#916
• [ ] Recheck IsValidImplementationFieldType and IsSubType algos
  • graphql/graphql-spec#977
• [ ] Recheck interface fields and arguments covariance
  • graphql/graphql-spec#974
• [x] Recheck argument name uniqueness
  • Checked: covered by unique_argument_names validation rule
  • graphql/graphql-spec#891
• [x] ~~Ensure root types are named properly~~ (generated SDL always has schema definition)
  • graphql/graphql-spec#987
• [x] Recheck selection set cannot be empty
  • Checked: empty selection set returns parsing error
  • graphql/graphql-spec#1025
• [ ] Recheck lists coercion
  • #1362
  • graphql/graphql-spec#1057
• [ ] Support extensions in request
  • #1356
  • graphql/graphql-spec#976
• [ ] Recheck literals validation
  • #1362
  • graphql/graphql-spec#1118
• [x] ~~Adjust documentation of built-in scalars~~ (reverted in graphql/graphql-spec#1186)
  • graphql/graphql-spec#1037
• [x] ~~Adjust "execution result"/"response" terminology~~ (well enough already)
  • graphql/graphql-spec#1159
• [x] ~~Replace ExecuteSelectionSet with ExecuteCollectedFields~~ (not required)
  • graphql/graphql-spec#1039
• [ ] Support default value coercion rules
  • #1362
  • graphql/graphql-spec#793
• [ ] Recheck CoerceArgumentValues() hasValue
  • #1362
  • graphql/graphql-spec#1056
• [ ] Update links to September 2025 spec