
Benjie
Hello GraphQL fans! Welcome to episode 6 of Spec News

Jem
keeping you up to date with advances in the GraphQL Spec and related foundation projects.

Benjie
We're your bespectacled hosts: I'm Benjie

Jem
and I'm Jem.

Benjie
September's meeting included the new arrangements for the meetings going forward,

Jem
A discussion of a new RFC concerning the extensions property,

Benjie
@defer and @stream moved to Stage 2,

Jem
Calls for feedback on a number of smaller topics,

Benjie
And a presentation on the need for granular metadata in GraphQL.
[0:36] Meeting times and cadence

Jem
The meeting opened with a note that the Working Group meetings are changing from October. There will now be three GraphQL Spec Working Group meetings per month, two at 10:30am Pacific time on the first and third Thursday, targeting America and Europe, and another on the second Wednesday at 3:30pm Pacific time targeting America and the Asia Pacific.

Benjie
There will also be additional timeslots available on the alternate Thursdays to make space for the various GraphQL Subcommittees. The working group is still open to feedback on these new times, so get in touch - but we really hope this will increase engagement from people within the Asia Pacific timezones!
[1:17] Specifying an extensions property on requests

Jem
Now onto the meat of the discussions! First was Benjie with an RFC regarding the extensions property for GraphQL requests.

Benjie
The GraphQL Spec details the format of a response object. To enable GraphQL to evolve without conflicts, an extensions property can be included, containing arbitrary vendor-specific details. Errors also have an extensions property for similar reasons.
At the moment, the GraphQL Spec doesn't explicitly say what the structure of a request is, only what information is required to form a request.

Jem
However, the GraphQL over HTTP Spec does need to specify the request format. As part of that, to maintain compatibility with the ecosystem, it needs to specify an extensions property on requests which is not currently specified in the GraphQL spec itself.

Benjie
When we come to document GraphQL over other protocols

Jem
(such as websockets, server-sent events, and more)

Benjie
it will need to be defined again in each new spec. I've been considering if something about this definition should live in the main spec to centralise this definition.

Jem
David from Apollo confirmed this was an issue they have faced—they have been using the extensions field on requests for a while, and have had problems with strict servers rejecting requests which include it because it's not currently detailed by any spec—it's "unexpected"—

Benjie
—excuse the pun

Jem
The discussion concluded with two options: EITHER add an optional entry to the list of things in the GraphQL spec that make up a request, with a small section detailing its intent; OR leave it up to the sub-specifications to define it in a stricter way. More on this in a future episode!
[3:01] @defer and @stream is now Stage 2: Draft

Benjie
Second was Rob with an update on the eagerly anticipated defer and stream spec edits… and the changes are now OFFICIALLY STAGE TWO! Congratulations to Rob, Lilliana, and everyone else who has been working hard to make stream and defer a reality!

Jem
The latest issue in stream and defer was spotted by our own Benjie:

Benjie
It relates to the handling of non-nullable fields throwing errors as siblings of (rather than children of) stream and defer boundaries. The sibling non-nullable error should wipe out the selection set, but due to GraphQL's parallel execution the stream may already have started executing when the error is thrown and the stream wasn't being cancelled, leading to payloads arriving that reference paths that shouldn't exist. A number of potential solutions were discussed, so this should not prevent the proposal moving forward.

Jem
@stream/@defer is by far the most complicated addition to GraphQL since it was open sourced, so there's still some work needed in the form of developing and writing lots of support material to help it be adopted in the wider ecosystem. Now it's at Stage 2, that kind of work can commence.
[4:17] isSubType, resolveAbstractType and the "Expanding subtyping" RFC

Benjie
Moving on, Yaccov asked for feedback on three small modifications to the GraphQL spec:
isSubType,
resolveAbstractType and the "Expanding subtyping" RFC. These pull requests can be found in the main Spec repo (
isSubType,
resolveAbstractType) and
the Working Group repo. Lee marked the
isSubType PR as an editorial change and decided to merge it then and there in order to allow Yaccov to progress on his other discussions.
[4:44] The "schema" keyword

Jem
Whilst reviewing Roman's suggestion to remove a particular paragraph from the spec, Benjie spotted an issue in its wording which revealed ambiguity around when the "schema" keyword should be omitted from GraphQL SDL. Benjie has carefully rewritten the language here and in the neighbouring paragraph, and there's general agreement that after dropping a couple of words the fix should be implemented.
[5:08] Granular metadata in GraphQL

Jem
Finally, Lee suggested that Benjie present his slides detailing his argument for why there is a need for granular metadata in GraphQL.

Benjie
I feel this topic is currently being overlooked in the discussions around schema metadata, and yet could open up some significant improvements in the usefulness of schema introspection at runtime—for example allowing for dropdowns to be generated by enums, for dynamic tables to be generated from introspection data, or for pagination limits to be indicated via the schema introspection and respected by clients without requiring new versions of the clients to be released

Jem
(for example, mobile apps would not have to wait on App Store review to release these kinds of minor changes!)

Benjie

Jem
Lee suggested that it's quite common to block introspection queries, which may limit who can use this

Benjie
(though I feel that blocking introspection queries is security-through-obscurity at best, and more likely a false sense of security in most cases—persisted operations being a better solution in many cases).

Jem
Benjie stresses that whatever solution is reached by the metadata discussions should be careful not to limit these different use cases of GraphQL unless there's a very good reason to do so.

Benjie
And so, that brings us to the end of the meeting, and the end of the podcast, we bid you a fond farewell.

Jem
Bye for now!