Benjie
Hello GraphQL fans! Welcome to episode 4 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.
July 2022's working group meeting saw discussion around adding directives to existing enum values,
Benjie
adding "schema metadata" to SDL and introspection,
Jem
allowing recursion when resolving the concrete object type of a value representing an interface or union type,
Benjie
an update from the GraphQL-over-HTTP working group,
Jem
and an update on the defer and stream RFC.
[0:40] Action items
Benjie
Here we go!
First up, action items. There were two action items from June's meeting, both of which have been addressed:
- the composite schemas working group has been created and is due to meet on Thursday 14th July
- a number of discussions and pull requests have been created (and some merged) related to Roman's specification feedback.
Jem
From the backlog:
- The "deprecation of input values" has passed Lee's final editorial review and is now in the draft specification! 🎉
- Rob is still progressing the stream and defer RFC—more on that later.
[1:15] Adding directives to existing enum values
Benjie
On to the main agenda.
Jem
This month's first topic came from new Working Group member Benoit. Benoit wants to control how enums are mapped into their native values on certain clients. To do this, he wishes to use the GraphQL "type extensions" syntax to add directives to existing enum values.
Benjie
The type extensions syntax in GraphQL allows you to add directives to existing types and to add enum values to enum types, but it does not allow you to add directives to existing enum values of an enum type. Similarly, it does't allow you to add directives to an existing field of an object or interface type, even though it can be used to add new fields.
Jem
Lee explained that the type extensions capability in GraphQL is deliberately very simple. If we were to enable this behaviour on enum values, we'd also expect to have this behaviour on object type fields, which are complex due to field arguments.
Michael suggested a custom merge strategy and Matt shared that Facebook uses a custom merge strategy with client-only schema files. Lee suggested the group should revisit the problem itself rather than the proposed solution—perhaps there's other ways to apply this metadata to the enum values without using the type extensions syntax. In chat many expressed that this might be a good topic for the composite schemas working group. Stephen shared that Shopify has a dedicated system they use internally for merging metadata back into the schema which allows for different teams to own different parts of the metadata.
Benjie
Hopefully Benoit will return to a future working group meeting with an updated proposal inspired by this feedback.
[2:53] Schema metadata
Benjie
Next up was the eagerly awaited presentation from Ivan on adding schema "meta" fields to the SDL and introspection.
In his presentation, Ivan showed that there are currently two main approaches to add metadata to a GraphQL schema. One is the "SDL" approach—as used in Apollo Federation—where the schema contains a string field containing a GraphQL document composed of the schema definition and additional metadata in the form of directives. The other is the "applied directives" approach—as used in GraphQL Java, Hot Chocolate and others—whereby directives applied when building the GraphQL schema would be exposed through the introspection schema.
Jem
Ivan noted Benjie did a
great talk on the need for GraphQL Schema metadata at the recent GraphQL Conference—there's a link in this episode's description.
Benjie
Focussing on the introspection direction, Ivan surfaced some of the shortcomings of the "applied directives" solution. One issue is that due to directives being repeatable and having significant order they would have to be exposed as a list, which is not an ideal way for clients to consume metadata.
Jem
Ivan suggested making metadata a first class citizen using the + symbol in SDL syntax and exposing via meta fields in introspection.
After a short break—
Benjie
I like this new trend!
Jem
—we returned on the hour for Roman to present his counter arguments, suggesting that we explore the appliedDirectives approach more thoroughly.
Benjie
Roman feels that directives are already metadata, the term being a "historical accident", and does not want to add another metadata approach. Further, he believes that since directives are committed to git, and git should not contain secrets, all directives are suitable to expose to end users.
Jem
Since the group were already well over time they agreed Ivan should raise a discussion thread and then moved on to the next topic.
[4:45] Allowing recursion within ResolveAbstractValue
Jem
Yaacov suggested a small change to the specification to allow for the ResolveAbstractType algorithm to enable recursion—motivated by the new "interfaces implementing interfaces" feature of GraphQL.
Benjie
This ResolveAbstractType algorithm is responsible for taking a runtime value associated with an abstract type (i.e. an interface or union) and figuring out which concrete object type the value represents.
Currently the specification states:
Return the result of calling the internal method provided by the type system for determining the Object type of abstractType given the value objectValue.
Jem
Yaacov suggested this "internal method" could return an intermediate type and have GraphQL recurse, rather than having to return the final object type directly (perhaps via recursion in user space).
Benjie
The group were still running short on time, so no specific conclusion was reached but Lee and others will give some feedback on the pull request.
[5:41] GraphQL over HTTP
Jem
Next up was Benjie with a small update from the GraphQL over HTTP subcommittee
Benjie
After an extended hiatus, we were interested in pumping some life back into this subcommittee. I kicked us off by rewriting the draft specification with a focus on backwards compatibility and introducing a watershed date of 1st January 2025.
Jem
The watershed states that from this date all GraphQL services must support the new application/graphql+json media type which would finally allow for GraphQL errors to safely be included in non-200 status code HTTP responses.
Benjie
Other members of the subcommittee have weighed in to help us get the spec much closer to being release worthy. The GraphQL-over-HTTP subcommittee met in June for the first time since 2020 and are due to meet again on 21st July with the aim of working towards releasing v1 of the GraphQL-over-HTTP specification with the next release of the GraphQL specification (which might be in October, judging by the last release).
Jem
That's a pretty tight deadline! Good luck!
[6:47] Update on defer/stream
Jem
Due to running short on time, a quick agenda modification meant that Rob was up next with updates from the defer and stream RFC. Recent work has focussed around batching of payloads to help avoid the client thrashing issues of delivering many small payloads in quick succession to a client. A general consensus has been reached on this topic, the introduction of the "incremental" field into the response payload, but the specifics around this are still being worked out.
Benjie
There was a long discussion around whether this change meant that we should change the "SHOULD" to a "MUST" when it comes to requiring the server to honour stream/defer directives in the request. Team MUST suggested many potential shapes for the response was undesirable, requiring the client to do more work. Team SHOULD felt the server understands the data better and should be able to determine whether to inline the data or return it via incremental patches. Another comment suggested an edge cache would forward the streamed response the first time, but then immediately return the resolved data object in later requests for both client and server efficiency. General consensus seems to be that we should keep it as a SHOULD for now, but it's not the 100% consensus that the group generally seeks.
Jem
Finally Rob asked for contributions to
discussion #42 on the defer-stream-wg repo, discussing the (rather bike-sheddy) topic of whether they should rename "data" to "items" when it comes to stream, since it returns a list rather than an object.
[8:18] Outstanding items
Benjie
Unfortunately we did not have time to cover the remaining topics which were Roman with an update on the changes he'd like to see in the structure of the GraphQL specification, and my proposal for a
"Structured, Type-safe, Returnable and Union Capable Type" (i.e. the "struct" type—a composite type suitable for use on both input and output and capable of polymorphism) and how this might weigh in to the metadata discussions. We'll open some
async discussions on these topics and hopefully will have time to discuss them at the next meeting.
Jem
As a final side note, asynchronous discussions over increasing the duration or cadence of GraphQL Spec WG meetings are still ongoing so that they can avoid having to skip topics like this in future—get involved on graphql-wg
discussion thread 1051!
Benjie
Phew! That was a packed meeting! That's all from us at Spec News and we bid you a fond farewell.
Jem
Ciao for now!