Skip to content

Commit 4269caf

Browse files
mjmahoneJoviDeCroock
authored andcommitted
RFC: Fragment Arguments
1 parent b5ecff0 commit 4269caf

File tree

4 files changed

+307
-52
lines changed

4 files changed

+307
-52
lines changed

spec/Appendix B -- Grammar Summary.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -170,12 +170,12 @@ Arguments[Const] : ( Argument[?Const]+ )
170170

171171
Argument[Const] : Name : Value[?Const]
172172

173-
FragmentSpread : ... FragmentName Directives?
173+
FragmentSpread : ... FragmentName Arguments? Directives?
174174

175175
InlineFragment : ... TypeCondition? Directives? SelectionSet
176176

177-
FragmentDefinition : fragment FragmentName TypeCondition Directives?
178-
SelectionSet
177+
FragmentDefinition : fragment FragmentName VariablesDefinition? TypeCondition
178+
Directives? SelectionSet
179179

180180
FragmentName : Name but not `on`
181181

spec/Section 2 -- Language.md

Lines changed: 65 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -520,10 +520,10 @@ which returns the result:
520520

521521
## Fragments
522522

523-
FragmentSpread : ... FragmentName Directives?
523+
FragmentSpread : ... FragmentName Arguments? Directives?
524524

525-
FragmentDefinition : fragment FragmentName TypeCondition Directives?
526-
SelectionSet
525+
FragmentDefinition : fragment FragmentName VariablesDefinition? TypeCondition
526+
Directives? SelectionSet
527527

528528
FragmentName : Name but not `on`
529529

@@ -1219,13 +1219,70 @@ size `60`:
12191219

12201220
**Variable Use Within Fragments**
12211221

1222-
Variables can be used within fragments. Variables have global scope with a given
1223-
operation, so a variable used within a fragment must be declared in any
1224-
top-level operation that transitively consumes that fragment. If a variable is
1225-
referenced in a fragment and is included by an operation that does not define
1226-
that variable, that operation is invalid (see
1222+
Variables can be used within fragments. Operation-defined variables have global
1223+
scope with a given operation, so a variable used within a fragment must either
1224+
be declared in any top-level operation that transitively consumes that fragment,
1225+
or by that same fragment as a fragment variable definition. If a variable is
1226+
referenced in a fragment is included by an operation where neither the fragment
1227+
nor the operation defines that variable, that operation is invalid (see
12271228
[All Variable Uses Defined](#sec-All-Variable-Uses-Defined)).
12281229

1230+
## Fragment Variable Definitions
1231+
1232+
Fragments may define locally scoped variables. This allows fragments to be
1233+
reused while enabling the caller to specify the fragment's behavior.
1234+
1235+
For example, the profile picture may need to be a different size depending on
1236+
the parent context:
1237+
1238+
```graphql example
1239+
query withFragmentArguments {
1240+
user(id: 4) {
1241+
...dynamicProfilePic(size: 100)
1242+
friends(first: 10) {
1243+
id
1244+
name
1245+
...dynamicProfilePic
1246+
}
1247+
}
1248+
}
1249+
1250+
fragment dynamicProfilePic($size: Int! = 50) on User {
1251+
profilePic(size: $size)
1252+
}
1253+
```
1254+
1255+
In this case the `user` will have a larger `profilePic` than those found in the
1256+
list of `friends`.
1257+
1258+
A fragment-defined variable is scoped to the fragment that defines it.
1259+
Fragment-defined variables are allowed to shadow operation-defined variables.
1260+
1261+
```graphql example
1262+
query withShadowedVariables($size: Int) {
1263+
user(id: 4) {
1264+
...variableProfilePic
1265+
}
1266+
secondUser: user(id: 5) {
1267+
...dynamicProfilePic(size: 10)
1268+
}
1269+
}
1270+
1271+
fragment variableProfilePic on User {
1272+
...dynamicProfilePic(size: $size)
1273+
}
1274+
1275+
fragment dynamicProfilePic($size: Int!) on User {
1276+
profilePic(size: $size)
1277+
}
1278+
```
1279+
1280+
The profilePic for `user` will be determined by the variables set by the
1281+
operation, while `secondUser` will always have a profilePic of size 10. In this
1282+
case, the fragment `variableProfilePic` uses the operation-defined variable,
1283+
while `dynamicProfilePic` uses the value passed in via the fragment spread's
1284+
argument `size`.
1285+
12291286
## Type References
12301287

12311288
Type :

0 commit comments

Comments
 (0)