Proposal: Add supported GraphQL spec version to introspection

[jimkyndemeyer]

As the spec evolves, and breaking changes come into play, it's increasingly difficult to build IDE plugins and other tooling that "just works" with various endpoint libraries that support different versions of the spec.

I've seen this numerous times in the issues I get for JS GraphQL IntelliJ plugin, and I believe that graphiql also has a number of workarounds to try and support introspection across multiple spec versions.

My suggestion is to add a new top level field that complements __schema and the other introspection fields. This field could be called something like __specs and would return a chronological list of the versions that the endpoint supports.

Tools/IDEs would initially do a {__specs} query to determine the version supported, and could then send a supported version of an introspection query. In case the specs field is not present, a validation error will be returned by the server, and June 2018 or older is assumed.

Thoughts, comments?

[IvanGoncharov]

As the spec evolves, and breaking changes come into play,

@jimkyndemeyer June 2018 is a first stable release of the spec:

The June 2018 edition of the GraphQL specification represents extensive refinement and improvement by the editors and community. It is the first edition to no longer be considered a "Draft RFC" (4cd6824) to reflect its extensive use in production. GraphQL continues to become a "stable base" atop which many companies have built new an interesting things.

Starting from that release we shouldn't introduce any breaking changes:
https://github.com/facebook/graphql/blob/master/CONTRIBUTING.md#guiding-principles

Once a query is written, it should always mean the same thing and return the same shaped result. Future changes should not change the meaning of existing schema or queries or in any other way cause an existing compliant GraphQL service to become non-compliant for prior versions of the spec.

Tools/IDEs would initially do a {__specs} query to determine the version supported, and could then send a supported version of an introspection query. In case the specs field is not present, a validation error will be returned by the server, and June 2018 or older is assumed.

We already discussed it on WG and it conflicts with our RFC procedure:
https://github.com/facebook/graphql/blob/master/CONTRIBUTING.md#rfc-contribution-stages

We need to able to experiment we adding new fields to introspection at Stage 2:
https://github.com/facebook/graphql/blob/master/CONTRIBUTING.md#stage-2-draft

That means we can't tie the existence of new fields to official spec releases.
During WG Lee suggested implementing two-stage introspection.
We didn't discuss specifics but I think the first query can look like this:

{
  Schema: __type(name:"__Schema") {
    fields {
      name
    }
  }
  Type: __type(name: "__Type") {
    fields {
      name
    }
  }
  # ...
}

And based on fields that are present, second introspection query will be formed.

I plan to implement this in graphql-js after 14.2.0 release.

PS. I also think two stage introspection is an excellent way to allow extensions inside introspection types, similar to extensions inside GraphQL response. I'm currently working on this proposal but I think we need to gather some real-world experience with two-stage introspection before we seriously discussing it.

[jimkyndemeyer]

Hi Ivan.

Thanks for the detailed response.

It's great to hear that there's thinking in this area. What I'm really after is the best possible developer experience. The guiding principles along with a focus on non-breaking changes post-June 2018 appears to address the issue of incompatible introspection queries for now.

I'll close the issue on that basis.

[victorandree]

@IvanGoncharov I think the ability to extend the introspection schema is very interesting, as a way to, for example, expose effects of custom directives in a way which isn't tied to SDL. I stumbled upon this 2-step approach in this issue – but can't seem to find any issue dedicated to this task.

Do you know if it's actively being worked on? Simply the ability to swap the __Schema type would be ... fantastic for more powerful introspection – but in graphql.js it's tied to the implementation of getFieldDef as part of executing a query. I can see how this could replace the need for Apollo Federation's { _service { sdl } } implementation when coupled with graphql/graphql-js#1527 to support custom extensions.

Sorry for hijacking this issue.

[benjie]

@victorandree I believe this is related to your issue: #300