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" (RFC: OneOf Input Objects graphql/graphql-spec#825)
• Schema coordinates as a standard for GraphQL tooling and reporting (Schema Coordinates graphql/graphql-spec#794)
• Descriptions on documents, in motivation for AI-consumers (Add descriptions to executable documents | 2025 Update graphql/graphql-spec#1170)
• Broader support for deprecation across a GraphQL Schema (Allow deprecation of input values (field args, directive args, input fields) graphql/graphql-spec#805 Make the reason argument in @deprecated non-nullable graphql/graphql-spec#1040 graphql-spec#1053 make includeDeprecated non nullable graphql/graphql-spec#1142)
• GraphQL language has been updated to support the full Unicode range (RFC: Allow full unicode range graphql/graphql-spec#849)
• Countless editorial improvements! The spec is much easier to read and contribute to, with fewer ambiguities.

Roadmap

• Support @oneOf input objects
  • @oneOf input objects (#1062, #1055, #1347) #1354
  • Support of the @OneOf Input Object feature #1062
  • Feature Request: Derivable custom input objects #1055
  • RFC: OneOf Input Objects graphql/graphql-spec#825
• Support full unicode range
  • Support description on documents and schema (#1347) #1349
  • RFC: Allow full unicode range graphql/graphql-spec#849
  • allow full unicode range graphql/graphql-spec#687
• Support @deprecated on input values
  • Support deprecation of input object fields and arguments (#864, #1347) #1348
  • Feature request: support for deprecating input values #864
  • Allow deprecation of input values (field args, directive args, input fields) graphql/graphql-spec#805
• Make @deprecated(reason: ...) non-Null
  • Support deprecation of input object fields and arguments (#864, #1347) #1348
  • Make the reason argument in @deprecated non-nullable graphql/graphql-spec#1040
• Reject deprecated fields when interface field is not deprecated
  • Implementations may not deprecate a field that the interface hasn't deprecated graphql/graphql-spec#1053
• Make includeDeprecated field in introspection non-Null
  • Support deprecation of input object fields and arguments (#864, #1347) #1348
  • make includeDeprecated non nullable graphql/graphql-spec#1142
• Support description on documents
  • Support description on documents and schema (#1347) #1349
  • Add descriptions to executable documents | 2025 Update graphql/graphql-spec#1170
• Allow specifying schema description (already possible)
  • Support description on documents and schema (#1347) #1349
  • Do not exclude schema keyword if schema has description graphql/graphql-spec#1167
• Rename VariableDefinitions to VariablesDefinition
  • Rename VariableDefinitions to VariablesDefinition (#1347) #1353
  • Rename VariableDefinitions to VariablesDefinition graphql/graphql-spec#916
• Recheck IsValidImplementationFieldType and IsSubType algos
  • separate out IsSubType from IsValidImplementationFieldType graphql/graphql-spec#977
• Recheck interface fields and arguments covariance
  • P34: implementing field type is either exact match or of covariant type graphql/graphql-spec#974
• Recheck argument name uniqueness
  • Checked: covered by unique_argument_names validation rule
  • Add explanation about argument name uniqueness. graphql/graphql-spec#891
• Ensure root types are named properly (generated SDL always has schema definition)
  • Fix ambiguity around when schema definition may be omitted graphql/graphql-spec#987
• Recheck selection set cannot be empty
  • Checked: empty selection set returns parsing error
  • Clarify that selection sets cannot be empty graphql/graphql-spec#1025
• Recheck lists coercion
  • Revisit input coercion validation and execution rules (#1347) #1362
  • Fix coercion table for list graphql/graphql-spec#1057
• Support extensions in request
  • Support extensions in GraphQLRequest (#1347, graphql/graphql-spec#976) #1356
  • Add 'extensions' to request graphql/graphql-spec#976
• Recheck literals validation
  • Revisit input coercion validation and execution rules (#1347) #1362
  • Clarify 'Values of Correct Type' rule relates to literals graphql/graphql-spec#1118
• Adjust documentation of built-in scalars (reverted in condense the spec defs appendix graphql/graphql-spec#1186)
  • Add Appendix D - Specified Type System Definitions graphql/graphql-spec#1037
• Adjust "execution result"/"response" terminology (well enough already)
  • Define "execution result" and "request error result" graphql/graphql-spec#1159
• Replace ExecuteSelectionSet with ExecuteCollectedFields (not required)
  • Replace ExecuteSelectionSet with ExecuteCollectedFields graphql/graphql-spec#1039
• Support default value coercion rules
  • Revisit input coercion validation and execution rules (#1347) #1362
  • [RFC] Default value coercion rules graphql/graphql-spec#793
• Recheck CoerceArgumentValues() hasValue
  • Revisit input coercion validation and execution rules (#1347) #1362
  • Fix CoerceArgumentValues() hasValue graphql/graphql-spec#1056
• Update links to September 2025 spec