×

SpecNews #6

September 2022 WG

September's meeting included the new arrangements for the meetings going forward, a discussion of a new RFC concerning the extensionsproperty, @defer and @stream moved to Stage Two, calls for feedback on a number of smaller topics, and a presentation on the need for granular metadata in GraphQL.

Benjie's presentation is viewable on the GraphQL Federation Youtube channel: https://youtu.be/MEi1u6L__Ck?t=7148 The slides are also available at: https://is.gd/KmvX4e

Music by Zen_Man on Pixabay.

Transcript

Benjie
Benjie
Hello GraphQL fans! Welcome to episode 6 of Spec News
Jem
Jem
keeping you up to date with advances in the GraphQL Spec and related foundation projects.
Benjie
Benjie
We're your bespectacled hosts: I'm Benjie
Jem
Jem
and I'm Jem.
Benjie
Benjie
September's meeting included the new arrangements for the meetings going forward,
Jem
Jem
A discussion of a new RFC concerning the extensions property,
Benjie
Benjie
@defer and @stream moved to Stage 2,
Jem
Jem
Calls for feedback on a number of smaller topics,
Benjie
Benjie
And a presentation on the need for granular metadata in GraphQL.

[0:36] Meeting times and cadence

Jem
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
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
Jem
Now onto the meat of the discussions! First was Benjie with an RFC regarding the extensions property for GraphQL requests.
Benjie
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
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
Benjie
When we come to document GraphQL over other protocols
Jem
Jem
(such as websockets, server-sent events, and more)
Benjie
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
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
Benjie
—excuse the pun
Jem
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
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
Jem
The latest issue in stream and defer was spotted by our own Benjie:
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
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
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
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
Jem
Finally, Lee suggested that Benjie present his slides detailing his argument for why there is a need for granular metadata in GraphQL.
Benjie
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
Jem
(for example, mobile apps would not have to wait on App Store review to release these kinds of minor changes!)
Benjie
Benjie
The slides are linked in the podcast episode notes, they are designed to be readable without narration. (Youtube link: https://youtu.be/MEi1u6L__Ck?t=7148)
Jem
Jem
Lee suggested that it's quite common to block introspection queries, which may limit who can use this
Benjie
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
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
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
Jem
Bye for now!

Subscribe to be notified of new episodes of SpecNews:

« Back to episodes