2024-04.md

GraphQL WG Notes - April 2024

Watch the replays: GraphQL Working Group Meetings on YouTube

Primary

Agenda: https://github.com/graphql/graphql-wg/blob/main/agendas/2024/04-Apr/04-wg-primary.md

Determine volunteers for note taking (1m, Host)

• Jeff

Review prior secondary meetings (5m, Host)

• None

Review previous meeting's action items (5m, Host)

• Skipped

Note: ID must be serialized as String was merged (1m, Benjie)

• Benjie: we have wording in spec that ID should always serialize as String - I think that should be a must
• Benjie: actually an editorial
• Michael: on input we have polymorphic ids, could be encoded as [...]
• Benjie: this is only for serialization, doesn’t impact PR
• Lee: In ID section, there’s a bit on input coercion, will expect string and numeric literals - allowing people to drop quotes is a convenience. Good editorial change, we weren’t appropriately specific when drafting this. Should always probably should be swapped with must

Strict error paths (5m, Martin)

• Are we ready to merge graphql/graphql-spec#1073?
• Martin: same issue, error paths - should be vs. proposed change: must - important for nullability discussions
• Martin: discussing for months now, consensus - this was supposed to be the last checkpoint before merging
• Lee: let’s do it live [mashes merge button]
• 1492, 1499 closed by Benjie [mashes close button]
• 🧹

Define 'selection set' (5m, Benjie)

• Editorial PR
• Already 4 WG member approvals; aim: merge
• Benjie: selection set disambiguation - mutation vs. selection set within a mutation. Didn’t have any variables. Should make things a bit clearer. Don’t have a definition of selection set, drafted a short one - see PR
• Jeff: would be great for beginners/intermediate folks to get a more explicit understanding of the semantics
• Michael: @defer is there
• Benjie: kind of away from the core point here - (mentions that the incremental delivery working group are still determining how @defer might interact with mutation operations)
• Benjie and Lee: speaking about whether to repeat explanation in the algorithms section
• Lee: general pattern - double-colon styles, dictionary term, before we had that - this is a case where we weren’t linking to it - we were referring to the grammar. Are we comfortable with that sort of double-definition?
• Benjie: glossary vs. grammar is definitely ok - pull out grammar into glossary
• Lee: if we start doing this a lot, might end up being less helpful than we want, (talks about casing), could PascalCase it so we can define it in one place - define it once, transform it when it’s presented in other contexts
• Benjie: also applies to plurals - trying not to link to it. In spec.md you have a config file or something where you can reference external places - can also have aliases, equivalents - not major concern but does crop up
• Lee: markdown link syntax is also good. Food for thought - maintain principle of spec being easy to read and also cross-referencing where possible

Ordering of schema elements (10m, Benjie)

• RFC
• Question: should fields, input fields, arguments be defined as an "ordered map" rather than an "ordered set" (previously a "list")?
• Benjie: (reads out RFC)
• Lee: if you need validation, it’s not a characteristic of the data structure itself. But there are certain cases where validation does work e.g. can’t list something twice, must be unique
• Michael: so you’d rather say it’s an ordered list where the field name is unique?
• Lee: this is an interesting distinction where you’re producing distinct maps and sets - either bc it’s part of an internal algorithm or in preparation for delivering results to an operation - then you want to use a specific data structure because we’re describing constraints we want the algorithm to work on. But input data is either definitionally constrained because it was provided - list of variables is a map in JSON. But anything that gets parsed from a doc itself, into an operation, probably is a list. Grammatically allowed to say here’s a field w arguments: a: 1, a: 2, a: 3 - it’s invalid, doesn’t make sense, but it is grammatically correct and will parse. What allows us to have a helpful error message? If we were to parse as an ordered map? Is it replacing/erroring?
• Michael: in general, that’s true. Object type, schema type. It’s immutable over tim
• Lee: when it comes to spec text, not concerned w performance, once validated (...)
• Michael: what’s the main thing you’re doing: this is a list, typical use case of this - look something up by name in this case
• Benjie: input object is a map from a bunch of keys to a bunch of values - how do you take the input and coerce it into a given format? Doesn’t change that it’s still a map. In graphqljs you can’t define it, it’s a list of fields, will accept a map of fields. If in SDL you can repeat it, but it’s not an input object. SDL can be invalid, w/o it being an input object. In SDL it’s a list, not unique. Want to pass it semantically invalid. 100% agree w/ appendix - clarifies data structures, could be merged separately sooner
• Lee: makes sense. Definitely game to talk about messing w/ list vs. ordered set/map. Want to be careful we’re not describing a concept in a general sense. SDL grammar parsing vs. type system - territory where it’s quite fair, within type system you want to say this is an ordered set/map. Algorithm for SDL text to type system, if we were to do that, vast majority of time it’s context of query/mutation operation
• Lee: I like this change, do we all agree? Stick it to Stage 2 as a draft. Ask that we pop out Section 3, 4 vs. appendix A + GraphQL.md. (...) More, smaller RFCs preferred

Request extensions (10m, Benjie)

• RFC
• Previously: 2024-03-07, 2022-09-01 (video)
• Benjie: discussed this previously. 2022 discussed a few places where this could go - see above - decided on (B) more work :) so I did that
• Did not define that a request is a map but have effectively named each of the things
• We already do this anyway, execution request algorithm
• Added non-normative note about extensions
• Benjie: (continues to walk through RFC)
• Lee: changes in an “uncanny valley” bc of the way it’s currently defined (...) the problem we’re trying to solve is - in practice, this does get defined as a map, someone might add more data in that map that we might want to use in the future
• Benjie: perhaps more subtle than that - got HTTP request level stuff - doesn’t have schema in it - doesn’t have schema execution stuff, which you’re describing - graphqljs describes positional and object-based parameters, can pass either. V16 did away from that, now only accepts the map. Critically, inputs in map are different, also accepts other things like (...) there are various services that will want to use extensions - don’t want to reimplement in GraphQL Over X - it’s a map. A request itself isn’t a map, whether that’s exposed as a map or list isn’t important as much. Here’s the thing we’re going to feed the algorithm - nothing more
• Lee: if we formally defined execution request as a map with these key names, that constraint provides no value. Says “why,” here are the things you need in order to execute request. You can read this section as the type definition or doc text. Still uncanny valley bc extensions is defined, but is neither relative to where it comes from or where it goes. In response form it’s less so because it doesn’t say where it comes from, but still where it goes. If it gets serialized as JSON, here’s how it works. One degree of freedom more added here - wonder if simplest way to fix is to elaborate more in non-normative note, not the first reference to HTTP. Just to say it’s common you would pass these elements in as a map, the intent, then, of this field is to avoid overlap
• Stephen: different section we could add - difference between schema, etc. that aren’t coming from client, on the response, as you mentioned Lee, we talked a bit about server-to-client protocol - should we do that explicitly as a note on execution inputs?
• Lee: is the intent of this current section but could be more clear, not sure
• Stephen: there’s a de facto shape of json that comes from clients today - not the same as the fields here
• Benjie: what would you think of a PR that breaks this up into smaller parts? (...)
• Lee: sounds fine if you want to do that, this feels like, in defining this, makes sense to do a cleanup. The way you’ve redefine these bulletpoints is easier to read. Was prose before, this is step-by-step and easier to read. Separate editorial PR is fine. My actual thought on - trying to look in response - how much detail to go into on extensions. Not non-normative, it’s normative. You’re saying that it’s important that if you provide extensions, it’s got to be a map. Hey, there’s two real normative rules we’re introducing. No other data you can provide - this is the exclusive thing you’re doing. Response should have additional fields. Can allow it to be a bit fuzzy rather than defining in specific terms - wherever the input is coming from is clear, future-proof. Then extensions is the natural escape hatch from that
• Benjie: important note is that this has to do with the client - constraining what they can pass in. Do we use the term “client?” We use “service”
• Lee: I might make the case that resolvers - not sure how we’d frame context - are a property of the schema. Not usually how they author it though - they define an abstract schema. Pedantic interpretation could lead to confusion/conflict with examples
• Benjie (chat): https://github.com/graphql/graphql-js/blob/a81e6238fa3f3dd317cb33572dcc97020376c329/src/execution/execute.ts#L148-L158
• Lee: more prose explanation. We should explicitly say we don’t want you to add something not covered in spec - could get clobbered by us in the future. That’s the “why” behind this change
• Benjie: makes sense. Final question: L18, map reserved for implementors to extend protocol as they see fit - is “map” sufficient or must I say in a subsequent paragraph that “if extensions is provided, must be a map”
• Lee: yes, please add that. Suggestion is to replace non-normative note with normative text. It could come from anywhere, but don’t add anything that collides with non-future-proof keys

Announcements

• Benjie: GraphQLConf is here - tell your friends
• Michael: Composite Schemas WG talking about request/variable batching - pushing off protocol, batching to GraphQL Over HTTP - started refining the directives - talked about Fusion, Apollo, how do we want this distilled spec to look like w/ a couple of schema experiments. Working on directives we will use - refined shape that will take a couple of weeks. Will open a couple of PRs w spec tags on these use cases. Give ppl time to chime in. Would be great to hear from Netflix, get them to chime in. Making good progress, good group - lot of in-between discussions w each other
• Benjie: I host monthly primary meeting. Always v impressive, excellent work Michael and team - as always, graphql website is always looking for content - technical content - if anyone’s interested please do talk to me.
• Benjie: also GraphQL grant program - technical content, Foundation projects - apply directly, reach out to me, get some guidance, please reach out to me or Jory @ Linux Foundation
• Lee: all goes for your teams as well - if you wouldn’t mind going back to your group - signal boost! Conf talks, content ideas, grant proposals
• Benjie: Incremental Delivery WG has been doing work as well - Yaacov has been doing great work - Rob, is that something ppl can try out now?
• Rob: yes, quick update - going down path of @defer forking execution - how do fields inside and outside of defer multiple times, DoS problems - what does it look like w/o those issues - tons of examples. Inputs/outputs/tons of scenarios. Yaacov, Benjie helping out
• Michael: couple of iterations needed?
• Rob: getting closer, still work to do
• Benjie: transfer format - the syntax of what gets sent from client to server is broadly settled. Algorithms are under discussion
• Michael: did we change that format?
• Rob: not since mid- to late-2023
• Michael: initial version forked, now we dedup
• Rob: yeah
• Benjie: it’s a challenging change. Necessary bc potential security implications. Can be attacked easily
• Michael: (...)
• Benjie: Nullability WG has stalled a bit - different proposals are converging but general consensus is that one of them is good solution to underlying solution, perhaps a better solution than client-controlled nullability (CCN)
• Michael: Also a lot of mixed feelings on syntax - “new GraphQL” kind of thing - many like it a lot. Other syntax there is a lot of discussion
• Benjie: either you opt in via a top-level directive
• Michael: it’s very personal to people
• Benjie: unadorned = nullable, so ? doesn’t make sense
• Martin (chat): We released experimental @semanticNonNull support and the first question is always “when do we get proper syntax.?”
• Benjie: GraphQL.js WG is now distributed
• Michael: it’s fascinating how the work is now distributed
• Lee: Different models of work - sub WGs reporting up, or Primary flowing out