Deprecate includeDeprecated, add __schema(includeDeprecated:)

[benjie]

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.

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	3430819
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/6a2924e9d30e9e000877b83f
😎 Deploy Preview	https://deploy-preview-1230--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.

[BoD]

Could we go further and not add the __schema-level includeDeprecated argument? Rationale: it's just simpler to always get the full schema? I know this would be a larger departure from the status quo, but are there good use cases for includeDeprecated: false?

[benjie]

That would change the meaning of any existing queries that use introspection and don't specify includeDeprecated: true. It's going to be very hard to assert that such queries do not exist after this having existed for 11 years in the wild, I think.

[BoD]

Ahh yeah of course. What I really want is for includeDeprecated to default to true, but alas that would be breaking indeed.

[leebyron]

I really like this!

This makes it MUCH more clear that you're accessing one of two schemas: the super set including deprecated elements OR the subset without. That maps very cleanly to the single boolean