RFC: operation expressions #823
Conversation
|
cc @magicmark |
|
Thanks for the feedback @sungam3r; but I’m more interested in use cases and general reasons not to have a standard syntax like this rather than syntax specifics right now. We might replace any of the symbols or even change the grammar before this sees the light of day; the aim currently is to see if it’s worth investing time here. |
|
Great start! I have no concerns with the use cases so far. |
|
@benjie this looks awesome :) really love the idea. All in for it. |
|
@sungam3r All feedback addressed; I've also gone as far as to write out the full grammar in spec-md format. |
|
Added to the next WG agenda; main aim right now is to collect more use cases. The main motivation for doing this now is to make sure that the Schema Coordinates RFC syntax is extensible. So far, I feel that it is. |
|
@benjie From all your examples it follows that we are always talking about a single field. It was not clear to me at first, especially when I read about generated queries. I began to wonder how to make it possible to specify more than one field in the generated request. As I understand it, in no way, because this is not the goal. The goal is to give the coordinate of one field, and the generated request is an additional feature. Correct? |
|
@sungam3r I'm still gathering use cases, so if you have a use case for multiple fields I'd love to hear it and we could potentially expand the syntax to incorporate that. However in general for referencing multiple fields it feels like we already have a query syntax that handles that: GraphQL itself. Currently all the examples in this PR relate to referencing a single field; but what I'd really like to see is all the different ways that we might build upon the syntax from the Schema Coordinates RFC. If there are use cases that require extensions to the Schema Coordinates syntax but don't relate to fields, I'd absolutely love to hear them! Don't let your imagination be limited by the few examples I've added, nor by the syntax I've added to address these examples. |
|
|
||
| ## Use cases | ||
|
|
||
| #### Referencing a position within a GraphQL Operation Document |
There was a problem hiding this comment.
pedantic question: should this be "Referencing a position within a GraphQL Query"?
asking cos what if the document contains two operations? does the operation expression encode which operation in the document it refers to? (can it / should it?)
There was a problem hiding this comment.
Yes it can, via the name:
OperationName:mutation>createFoo>foo>id
| These are all valid operation expressions, but they each convey different levels | ||
| of context. |
There was a problem hiding this comment.
I really like this - i could imagine being able to specify different levels of verbosity to tooling that generates these
| Emmet is a popular syntax for quickly generating HTML/CSS. It's easy to imagine | ||
| how a operation expression syntax could be combined with a GraphQL schema | ||
| definition to quickly generate GraphQL queries, mutations and subscriptions with | ||
| a concise syntax. For example the expression: |
There was a problem hiding this comment.
How lossy is this? If I converted a query to an operation expression and then back again to a query, is it always perfectly preserved? (Wondering how things like @if are preserved, or directives in general)
There was a problem hiding this comment.
Directives are out of scope currently (though I can imagine them being added, repeatable may be an awkward syntax) and it currently only maps one field/entity/path so cannot contain multiple fields like a query would.
| We also allow `[number]` syntax to refer to a numbered entry in a list, or `[]` | ||
| to refer to the next entry; e.g.: | ||
|
|
||
| `>findUsers(byIds[]:,byIds[],byIds[],byIds[5])>name` |
There was a problem hiding this comment.
i'm a little confused here - are we implying that byIds5 is an array?
(it's written as a single ID type in the query below)
And does it make sense to refer individual members of an input array?
Sorry for being dumb here!
There was a problem hiding this comment.
The auto-variables may be adding some confusion here. The byIds: argument is a list, so we can specify members of it; since they have no values if we want to have it converted to a document we need to pass something so we automatically generate variables for it; in this case $byIds5 (an ID, not a list) is one of the members of the list that’s fed to byIds:
There was a problem hiding this comment.
@benjie this looks amazing! Thanks for this huge effort (as always :P)
Wondering if we should add a non-goals or open questions section to clarify a couple of thoughts (and I imagine others) had:
- Should this syntax support selecting multiple leaf nodes with commas? Wildcard selectors?
- Should this take directives into account? (I'm having a hard time imagining what the use case here would be / what that looks like)
Other than that, the direction/syntax here looks good to me :)
|
I see enums are described as supported, but not called out as an example or in the list of grammar support. Should there be an example? |
|
@magicmark I can't see the term |
leebyron
force-pushed
the
main
branch
4 times, most recently
from
e5d241d to
6c81ed8
Compare
|
Merging in advance of moving the RFCs to a new repo |
benjie
added
📣 RFC document
Relates to graphql/graphql-wg#592
This RFC is to act as a discussion place for operation expressions; an extension to the Schema Coordinates syntax that allows for a host of new use cases.
I've outlined some of the use cases that have been discussed so far, and have iterated on the syntax a little, but everything in this is very much in flux. The purpose of this PR is to be a place to host the discussion (separate from Schema Coordinates) so that others may bring their ideas to the table. I don't think it's suitable for merging at this time.
See the document rendered nicely here.
Grammar support: