Deprecate includeDeprecated, add `__schema(includeDeprecated:)`

At a glance

• Identifier: #1230
• Stage: RFC 0 / Strawman
• Champion: @benjie
• Latest activity: Added to WG agenda on 2026-07-02
• Spec PR: https://github.com/graphql/graphql-spec/pull/1230

Spec PR description

Introspection should describe a consistent schema. The rules of the GraphQL schema validation aim that there are at least two consistent schemas (PR to follow to make this more explicit...): the source schema, and a derived schema that has all deprecated elements removed. Currently, however, an inconsistent schema can be described by mixing different values into includeDeprecated arguments throughout introspection. Worse, because includeDeprecated defaults to false, every time a new feature of the schema can be deprecated, existing schema introspection queries can start to represent an invalid schema as newly deprecated entities may be excluded even though includeDeprecated: true is specified for all previous introspection fields.

This PR aims to eliminate this inconsistency by deprecating the old includeDeprecated: system and replacing it with a __schema-level includeDeprecated argument that applies recursively. This however requires some further changes:

• Other includeDeprecated arguments would conflict with the __schema-level includeDeprecated, so they are forbidden when it's specified.
• Since includeDeprecated is false by default, specifying __schema(includeDeprecated: true) would still describe the un-deprecated portions of the schema; thus the existing includeDeprecated arguments must lose their default value and become optional (which currently means nullable).

Were it the case that includeDeprecated had had the default value true throughout history, this change could have been accomplished by simply adding __schema(includeDeprecated: Boolean! = true), since {__schema(includeDeprecated: false) {...}} would represent a schema with all deprecated elements removed independent of any nested includeDeprecated arguments. Alas, we defaulted to false and thus to allow includeDeprecated: true at the root level we need to put in more effort.

Possible expansion: we could make the validation rule stricter: forbid literal null, and require that a variable in that position is defined as non-nullable. I didn't see sufficient value in this to justify adding it, but I'm happy to do so if others think it's worthwhile.