Benjie
Welcome to episode 3 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.
June 2022's working-group-meeting saw the closure of a number of action items
Benjie
the introduction of a new "composite schemas" working group
Jem
a discussion around an @experimental directive
Benjie
a new validation rule to assert operation types exist
Jem
an update on the client-controlled nullability, @oneOf, and "unions implementing interfaces" RFCs
Benjie
and a number of spicy takes on the GraphQL spec itself—let's get into it!
[0:45] Action items
Jem
First up: action items. Benjie has added a SECURITY document to the .github repo so all foundation projects now have a security policy. Further, he submitted an editorial PR clarifying that the term "request" is independent of transport—i.e. it does not refer to an HTTP request.
Benjie also raised awareness of a suggestion to either increase the length of the working group meetings, or to increase their cadence, and predicted that this meeting would overrun. Before March 2021, the meetings were 3 hours long, but were shortened to 2 hours to help make attendance easier. Further discussion should take place in working group issue #988.
[1:30] Composite schemas working group
Benjie
The composite schemas working group was proposed by yours truly—a working group to look at the commonality between all the various "composite schema" approaches: stitching, merging, federation, joins, etc. It gained significant interest and all the key players were already on board when the spec working group officially approved it as a subcommittee. Interested parties should add themselves to the
RFC document via pull request, and an initial meeting will be announced in the next few weeks.
[2:02] @experimental directive
Jem
New attendee Martin has proposed a new @experimental directive—
Benjie
that's a directive named "experimental"
Jem
—which is the counterpart of deprecated. Where @deprecated marks a previously stable field as one which you should no longer use, @experimental marks a new field as unstable and so not suitable for production usage yet.
There was a lot of interest and discussion around the proposal, with comments indicating similar functionality was already in use at GitHub, Netflix and other companies; showing it's definitely a need. Next steps are to explore alternative solutions, such as creating an @opt-in directive—
Benjie
that's a directive named "opt-in"
Jem
—which could work a little like feature flagging.
[2:48] Add validation rule that operation types exist
Benjie
Another new attendee, Ben, has pointed out that the GraphQL Spec doesn't have a validation rule to prevent mutation operations against a schema that does not support mutations; of course they won't actually execute, but this lack of validation causes confusing results in tooling.
Ben has proposed to add this simple validation rule and it immediately jumped to RFC1 without any pushback; I imagine it has a very good chance of becoming RFC2 at the next working group since it already has an implementation in place.
[3:19] Client-controlled nullability update
Jem
Client-controlled nullability champion Alex has raised discussion threads around both
the naming of the RFC itself, and around
the naming of the symbols in the AST.
Benjie
For those unfamiliar, client-controlled nullability was originally proposed to allow the client to indicate that it wanted to override the nullability of a given field by applying an operator to it, though it's evolved since then to be more akin to try-catch, hence the search for a new name.
Jem
Whilst giving us an update, Alex let us know that the operators now need to strictly match during field merging; a restriction that wasn't previously the case. Though Relay plans to strip the operators before sending to the server, this may cause issues for other clients that rely on fragment isolation. Alex will be providing more details about it soon.
Benjie
And then something unprecedented happened… we voted through the power of emoji to take a 4 minute break!
[4:15] @oneOf update
Jem
Returning to the meeting, Benjie gave an update on the @oneOf input objects RFC. This RFC achieved RFC2 during the May working group, and is currently flirting with RFC3—though it's not getting anywhere yet!
A couple of small changes were made: the introspection field oneOf was renamed to isOneOf to match isDeprecated, and a rule was added forbidding @oneOf to be applied to an input object extension. Benjie also raised a draft PR for @oneOf objects—
Benjie
i.e. @oneOf for outputs rather than inputs
Jem
—and that was immediately marked RFC zero. The purpose of this work in progress RFC was to determine if there was likely to be any inconsistencies between an input @oneOf and an output @oneOf; the main outcome of which was questions around whether the unselected fields must be omitted, or can be included but null.
The desire is still to omit them, but it was worth the investigation.
The working group are still uncertain around the expressed nullability of @oneOf input fields, this still seems to be the main sticking point. A suggestion around changing the representation of @oneOf in the SDL syntax was quickly shot down, a directive is the preferred approach due to the reduced complexity there.
[5:39] Unions implementing interfaces
Benjie
Yaacov returned with an update on "unions implementing interfaces". There was a question around the fields introspection property for a union that implements interfaces; normally a union does not have fields, but as Lee points out everything that implements interfaces right now must also declare its fields. To progress this RFC further, Yaacov must demonstrate that the value added by the feature outweighs the additional complexity it introduces.
Yaacov then went on to talk about an alternative proposal—the ability to include interfaces and unions within a union.
Jem
Currently unions may only contain concrete object types, not abstract types.
Benjie
Yaacov feels that this change would be simpler, but the non-obvious introspection consequences made Lee rather nervous. Though schema build tooling could mostly handle this concern, there is value in reflecting the underlying unions and interfaces through introspection as it may improve legibility of the API in tools such as GraphiQL. Yaacov commented that his main motivations are addressing the needs that people are expressing via the GraphQL Spec issues repository, so even if we don't solve these problems at least explaining why we haven't solved them would be a valuable outcome.
Jem
Valuable indeed!
[6:58] Editorial changes to the Spec
Jem
Next up was Roman who recently
filed a discussion against the GraphQL Spec containing 29 small issues in the spec. Lee advised that splitting the issues into smaller pull requests and issues, one per topic, would make them much easier to address as it would be much easier for people to weigh in. More in-depth issues could be raised as proposals.
Benjie
Roman went on to give a 10 minute presentation on the issues he saw in the specification, sharing with the working group his understanding of the publishing industry, suggesting significant restructuring of the specification and a number of spicy takes including suggesting that many of the algorithms in the specification should be removed in order to make it shorter and to "not offend programmers".
Jem
Unfortunately the meeting overran so there wasn't much time to discuss these takes, nor to hear Ivan's eagerly awaited proposal to solve adding metadata to the introspection system, but I'm sure we'll have time for these things in future working groups.
Benjie
And with that, that's all from us at Spec News and we bid you a fond farewell.
Jem
Laters gators!