Full schemas: umbrella discussion

[martinbonnin]

In order to do proper validation and feature detection, tools like clients and/or IDE plugins need to get more information than just what the source SDL schema is. For an example they need to know if __InputValue.isDeprecated is present and for this require access to some of the built-in types.

This information is available in introspection but the introspection format has disadvantages. It's less compact and generally less readable/editable. Someone navigating to a field definition in their IDE would have a hard time reading introspection JSON.

Using SDL for this purpose would be nice. But this is use case is not really represented in the specification.

Someone taking the introspection results and transforming them to SDL would produce a schema that is not spec compliant because of this:

When representing a GraphQL schema using the type system definition language, all built-in scalars 
must be omitted for brevity.

There are other places that mention omitting the built-in directives, which is not desirable for this use case.

This proposal is about recognizing that the GraphQL language can be used for other purposes than being a source for implementations and defining what constitutes a valid full schema.

This discussion tracks smaller discussions/items. I'll update it as we go.

Current items:

• Appendix C - built-in definitions (graphql-spec/pull/1037)
• Terminology: introduce sourceSchemaDocument and fullSchemaDocument, bikeshed the names (glossary, spec-edits)

Todo:

• Terminology: SDL vs Type System Definition Language vs GraphQL
• Terminology: Service vs Implementation
• ... more stuff ...
• Spec edits
• Profit!

References:

• Oct WG: https://github.com/graphql/graphql-wg/blob/main/notes/2023/2023-10.md#full-schemas-15min-martin
• Oct WG action item: [2023-10] Everyone - please review Full Schemas RFC #1415
• Sep WG: https://github.com/graphql/graphql-wg/blob/main/notes/2023/2023-09.md?plain=1#L32
• Aug WG: https://github.com/graphql/graphql-wg/blob/main/notes/2023/2023-08.md#sdl-omissions-martin
• Aug WG action item: [2023-08] full schemas: write a RFC that captures the WG discussion and a possible way forward #1367
• Initial PR: Add a note about omitting introspection type definitions graphql-spec#1036
• Initial RFC: https://github.com/graphql/graphql-wg/blob/main/rfcs/FullSchemas.md

[benjie]

I think __schema and __type should definitely be included in the full schema, and I'm okay with __typename being included too since it's a machine-written schema and intended to be read by machines too (seems like it wouldn't be a "full schema" without __typename).

[martinbonnin]

👍 then we'll definitely need the introspection parts.

Also I just realized we probably won't spare the metadata in introspection discussion because of stuff like @oneOf. It's not strictly speaking validation but the codegen will need access to the applied @oneOf directive if we want to model the input objects a bit better than what we currently do.

[benjie]

oneOf is already represented in SDL because it has a reflection in introspection, just like deprecated.

[benjie]

(Or at least it SHOULD be; I’ve not actually checked the graphql-js implementation of this.)

[benjie]

graphql/graphql-js#3969