Fragment Arguments (parameterized fragments) for GraphQL
At a glance​
- Identifier: #865
- Stage: RFCX: Closed 2023-01-19T18:31:34Z
- Champion: @mjmahone
- PR: Fragment Arguments (parameterized fragments) for GraphQL
- Related:
- #1010 (Fragment Arguments: Spec Implementation)
- FeatureDiscovery (Feature Discovery)
- FragmentModularity (Fragment Modularity)
Timeline​
- Commit pushed: Split RFC doc into graphql-wg PR on 2023-01-11 by @mjmahone
- Added to 2023-01-11 WG agenda
- 4 commits pushed on 2023-01-05:
- Added to 2023-01-05 WG agenda
- Commit pushed: Fragment Arguments added to spec on 2023-01-02 by @mjmahone
- Mentioned in 2023-01 WG notes
- Added to 2021-06-03 WG agenda
- Mentioned in 2021-06-03 WG notes
- Added to 2021-05-13 WG agenda
- Mentioned in 2021-05-13 WG notes
- Spec PR created on 2021-05-05 by mjmahone
- Commit pushed: text changes on 2021-05-05 by @mjmahone
This is a proposal to bring Relay-style Fragment Arguments into the Spec as an optional, client-only language feature.
Overview
We would allow clients to write GraphQL like:
query Q1 {
...Number(x: 100)
}
query Q2($i: Int = 3) {
...Number(x: $i)
}
fragment Number($x: Int!) on Query {
number(value: $x)
}which would, prior to sending to the server, be transformed into two unique queries that current spec-compliant servers would understand, such that it behaved like the queries were written like:
query Q1 {
...Number
}
fragment Number on Query {
number(value: 100)
}and
query Q2($i: Int = 3) {
...Number
}
fragment Number on Query {
number(value: $i)
}The exact mechanics of how the query gets rewritten could be different per client, but the behavior should be identical. This RFC seeks to describe the new syntax, as well as adding additional validation for clients that choose to support fragment arguments.
Background
Relay has seen a lot of usage of their non-spec-compliant
@arguments
and@argumentDefinitions
directives, but they're both cumbersome to use and fail basic Spec validation (directives with arguments used but never defined). They accomplish this by pre-compiling any GraphQL definitions using@arguments
and@argumentDefinitions
to transform the document such that, by the time it's sent to the server, it is spec compliant. However, Relay's user-facing directives both do not conform to the spec and also provide a pretty cumbersome, somewhat unintuitive user-facing design.This proposal is to allow clients that pre-compile their GraphQL prior to sending it to the server (such as Relay) to have a built-in syntax for passing argument values into fragment spreads for fragments with well-defined argument definitions.
Champion: @mjmahone