×

SpecNews #3

June 2022 WG

June 2022's working group meeting saw the closure of a number of action items, the introduction of a new "composite schemas" working group, a discussion around an @experimental directive, a new validation rule to assert operation types exist, an update on the client-controlled nullability, @oneOf, and "unions implementing interfaces" RFCs and a number of spicy takes on the GraphQL spec itself!

Music by Zen_Man on Pixabay.

Transcript

Benjie
Benjie
Welcome to episode 3 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.

June 2022's working-group-meeting saw the closure of a number of action items
Benjie
Benjie
the introduction of a new "composite schemas" working group
Jem
Jem
a discussion around an @experimental directive
Benjie
Benjie
a new validation rule to assert operation types exist
Jem
Jem
an update on the client-controlled nullability, @oneOf, and "unions implementing interfaces" RFCs
Benjie
Benjie
and a number of spicy takes on the GraphQL spec itself—let's get into it!

[0:45] Action items

Jem
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
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
Jem
New attendee Martin has proposed a new @experimental directive—
Benjie
Benjie
that's a directive named "experimental"
Jem
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
Benjie
that's a directive named "opt-in"
Jem
Jem
—which could work a little like feature flagging.

[2:48] Add validation rule that operation types exist

Benjie
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
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
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
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
Benjie
And then something unprecedented happened… we voted through the power of emoji to take a 4 minute break!

[4:15] @oneOf update

Jem
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
Benjie
i.e. @oneOf for outputs rather than inputs
Jem
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
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
Jem
Currently unions may only contain concrete object types, not abstract types.
Benjie
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
Jem
Valuable indeed!

[6:58] Editorial changes to the Spec

Jem
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
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
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
Benjie
And with that, that's all from us at Spec News and we bid you a fond farewell.
Jem
Jem
Laters gators!

Subscribe to be notified of new episodes of SpecNews:

« Back to episodes