Skip to content

Commit b4f3c5d

Browse files
committed
formatting and expand examples
1 parent 492c556 commit b4f3c5d

File tree

3 files changed

+62
-39
lines changed

3 files changed

+62
-39
lines changed

spec/Section 2 -- Language.md

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1220,12 +1220,13 @@ size `60`:
12201220
**Variable Use Within Fragments**
12211221

12221222
Variables can be used within fragments. Operation-defined variables have global
1223-
scope within a given operation. Fragment-defined variables have local scope within the
1224-
fragment definition in which they are defined. A variable used within a fragment must either
1225-
be declared in each top-level operation that transitively consumes that fragment,
1226-
or by that same fragment as a fragment variable definition. If a variable
1227-
referenced in a fragment is included by an operation where neither the fragment
1228-
nor the operation defines that variable, that operation is invalid (see
1223+
scope within a given operation. Fragment-defined variables have local scope
1224+
within the fragment definition in which they are defined. A variable used within
1225+
a fragment must either be declared in each top-level operation that transitively
1226+
consumes that fragment, or by that same fragment as a fragment variable
1227+
definition. If a variable referenced in a fragment is included by an operation
1228+
where neither the fragment nor the operation defines that variable, that
1229+
operation is invalid (see
12291230
[All Variable Uses Defined](#sec-All-Variable-Uses-Defined)).
12301231

12311232
## Fragment Variable Definitions
@@ -1279,10 +1280,10 @@ fragment dynamicProfilePic($size: Int!) on User {
12791280
```
12801281

12811282
The profilePic for `user` will be determined by the variables set by the
1282-
operation, while `secondUser` will always have a `profilePic` of size `10`. In this
1283-
case, the fragment `variableProfilePic` uses the operation-defined variable,
1284-
while `dynamicProfilePic` uses the value passed in via the fragment spread's
1285-
`size` argument.
1283+
operation, while `secondUser` will always have a `profilePic` of size `10`. In
1284+
this case, the fragment `variableProfilePic` uses the operation-defined
1285+
variable, while `dynamicProfilePic` uses the value passed in via the fragment
1286+
spread's `size` argument.
12861287

12871288
## Type References
12881289

spec/Section 5 -- Validation.md

Lines changed: 23 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -424,9 +424,10 @@ FieldsInSetCanMerge(set):
424424
- Let {spreadsForName} be the set of fragment spreads with a given name in
425425
{visitedSelections}.
426426
- For each {spreadsForName} as {name} and {spreads}:
427-
- Each entry in {spreads} must have identical sets of arguments to each other entry in {spreads}.
428-
- Let {fieldsForName} be the set of field selections with a given response name in
429-
{visitedSelections}.
427+
- Each entry in {spreads} must have identical sets of arguments to each other
428+
entry in {spreads}.
429+
- Let {fieldsForName} be the set of field selections with a given response name
430+
in {visitedSelections}.
430431
- Given each pair of members {fieldA} and {fieldB} in {fieldsForName}:
431432
- {SameResponseShape(fieldA, fieldB)} must be true.
432433
- If the parent types of {fieldA} and {fieldB} are equal or if either is not
@@ -602,8 +603,9 @@ the fragment spread `...commandFragment(command: SIT)` and
602603
`...commandFragment(command: DOWN)` are part of the visited selections that will
603604
be merged.
604605

605-
If both of these spreads would have `$commandOne` or `$commandTwo` as the argument-value,
606-
it would be allowed as we can be sure that we'd resolve identical fields.
606+
If both of these spreads would have `$commandOne` or `$commandTwo` as the
607+
argument-value, it would be allowed as we can be sure that we'd resolve
608+
identical fields.
607609

608610
### Leaf Field Selections
609611

@@ -699,8 +701,8 @@ validation rules apply in each case.
699701

700702
**Explanatory Text**
701703

702-
Every argument provided to a field or directive or fragment spread must be
703-
defined in the set of possible arguments of that field, directive or fragment.
704+
Every argument provided to a field or directive must be defined in the set of
705+
possible arguments of that field or directive.
704706

705707
For example the following are valid:
706708

@@ -712,7 +714,13 @@ fragment argOnRequiredArg on Dog {
712714
fragment argOnOptional on Dog {
713715
isHouseTrained(atOtherHomes: true) @include(if: true)
714716
}
717+
```
715718

719+
The above is also applicable to fragment-definitions and fragment-spreads, each
720+
variable must be defined by the fragment-definition before it can be inserted as
721+
an argument by the fragment-spread.
722+
723+
```graphql example
716724
fragment withFragmentArg($command: DogCommand) on Dog {
717725
doesKnowCommand(dogCommand: $command)
718726
}
@@ -738,6 +746,10 @@ and this is also invalid as the argument `dogCommand` is not defined on fragment
738746
fragment invalidFragmentArgName on Dog {
739747
...withFragmentArg(dogCommand: SIT)
740748
}
749+
750+
fragment withFragmentArg($command: DogCommand) on Dog {
751+
doesKnowCommand(dogCommand: $command)
752+
}
741753
```
742754

743755
and this is also invalid as `unless` is not defined on `@include`.
@@ -1620,8 +1632,8 @@ fragment HouseTrainedFragment on Query {
16201632
}
16211633
```
16221634

1623-
Likewise, it is valid for a fragment to define a variable with a name that
1624-
is also defined on an operation:
1635+
Likewise, it is valid for a fragment to define a variable with a name that is
1636+
also defined on an operation:
16251637

16261638
```graphql example
16271639
query C($atOtherHomes: Boolean) {
@@ -1989,7 +2001,8 @@ fragment fragmentArgUnused($atOtherHomes: Boolean) on Dog {
19892001
}
19902002
```
19912003

1992-
This document is invalid: fragment `fragmentArgUnused` defines a fragment variable `$atOtherHomes`, but this variable is not used within this fragment.
2004+
This document is invalid: fragment `fragmentArgUnused` defines a fragment
2005+
variable `$atOtherHomes`, but this variable is not used within this fragment.
19932006

19942007
### All Variable Usages Are Allowed
19952008

spec/Section 6 -- Execution.md

Lines changed: 28 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -340,7 +340,8 @@ ExecuteSelectionSet(selectionSet, objectType, objectValue, variableValues):
340340
- For each {groupedFieldSet} as {responseKey} and {fields}:
341341
- Let {fieldName} be the name of the first entry in {fields}. Note: This value
342342
is unaffected if an alias is used.
343-
- Let {fragmentVariableValues} be the fragment-variables value of the first entry in {fields}.
343+
- Let {fragmentVariableValues} be the fragment-variables value of the first
344+
entry in {fields}.
344345
- Let {fieldType} be the return type defined for the field {fieldName} of
345346
{objectType}.
346347
- If {fieldType} is defined:
@@ -493,21 +494,22 @@ The depth-first-search order of the field groups produced by {CollectFields()}
493494
is maintained through execution, ensuring that fields appear in the executed
494495
response in a stable and predictable order.
495496

496-
CollectFields(objectType, selectionSet, variableValues, visitedFragments, localVariableValues):
497+
CollectFields(objectType, selectionSet, variableValues, visitedFragments,
498+
localVariableValues):
497499

498500
- If {visitedFragments} is not provided, initialize it to the empty set.
499501
- Initialize {groupedFields} to an empty ordered map of lists.
500502
- For each {selection} in {selectionSet}:
501503
- If {selection} provides the directive `@skip`, let {skipDirective} be that
502504
directive.
503505
- If {skipDirective}'s {if} argument is {true} or is a variable in
504-
{localVariableValues} or {variableValues} with the value {true}, continue with the next {selection}
505-
in {selectionSet}.
506+
{localVariableValues} or {variableValues} with the value {true}, continue
507+
with the next {selection} in {selectionSet}.
506508
- If {selection} provides the directive `@include`, let {includeDirective} be
507509
that directive.
508510
- If {includeDirective}'s {if} argument is not {true} and is not a variable
509-
in {localVariableValues} or {variableValues} with the value {true}, continue with the next
510-
{selection} in {selectionSet}.
511+
in {localVariableValues} or {variableValues} with the value {true},
512+
continue with the next {selection} in {selectionSet}.
511513
- If {selection} is a {Field}:
512514
- Let {responseKey} be the response key of {selection} (the alias if
513515
defined, otherwise the field name).
@@ -527,7 +529,8 @@ CollectFields(objectType, selectionSet, variableValues, visitedFragments, localV
527529
- If {DoesFragmentTypeApply(objectType, fragmentType)} is {false}, continue
528530
with the next {selection} in {selectionSet}.
529531
- Let {localVariableValues} be the result of calling
530-
{getArgumentValuesFromSpread(selection, fragmentDefinition, variableValues, localVariableValues)}.
532+
{getArgumentValuesFromSpread(selection, fragmentDefinition,
533+
variableValues, localVariableValues)}.
531534
- Let {fragmentGroupedFieldSet} be the result of calling
532535
{CollectFields(objectType, fragmentSelectionSet, variableValues,
533536
visitedFragments)}.
@@ -566,24 +569,27 @@ DoesFragmentTypeApply(objectType, fragmentType):
566569
- If {objectType} is a possible type of {fragmentType}, return {true}
567570
otherwise return {false}.
568571

569-
getArgumentValuesFromSpread(fragmentSpread, fragmentDefinition, variableValues, fragmentArgumentValues):
572+
getArgumentValuesFromSpread(fragmentSpread, fragmentDefinition, variableValues,
573+
fragmentArgumentValues):
570574

571575
- Let {coercedValues} be an empty unordered Map.
572576
- For each {variableDefinition} in {fragmentDefinition}:
573577
- Let {variableName} be the name of {variableDefinition}.
574578
- Let {variableType} be the type of {variableDefinition}.
575579
- Let {defaultValue} be the default value for {variableDefinition}.
576-
- Let {argumentNode} be the node provided in the fragment-spread for {variableName}
580+
- Let {argumentNode} be the node provided in the fragment-spread for
581+
{variableName}
577582
- If {argumentNode} isn't present or is null
578583
- If {defaultValue} exists
579584
- Add an entry to {coercedValues} named {argumentName} with the value
580585
{defaultValue}.
581586
- If {variableType} is non-nullable raise a field-error
582-
- Let {hasValue} be {true} if {fragmentArgumentValues} or {variableValues} provides a value for the name
583-
{variableName}.
584-
- If {variableType} is non-nullable and {hasValue} is {false} raise a field-error
585-
- Add an entry to {coercedValues} named {argumentName} with the value
586-
found in {variableValues} or {fragmentArgumentValues}.
587+
- Let {hasValue} be {true} if {fragmentArgumentValues} or {variableValues}
588+
provides a value for the name {variableName}.
589+
- If {variableType} is non-nullable and {hasValue} is {false} raise a
590+
field-error
591+
- Add an entry to {coercedValues} named {argumentName} with the value found in
592+
{variableValues} or {fragmentArgumentValues}.
587593
- Return {coercedValues}.
588594

589595
Note: The steps in {CollectFields()} evaluating the `@skip` and `@include`
@@ -597,7 +603,8 @@ coerces any provided argument values, then resolves a value for the field, and
597603
finally completes that value either by recursively executing another selection
598604
set or coercing a scalar value.
599605

600-
ExecuteField(objectType, objectValue, fieldType, fields, variableValues, fragmentVariableValues):
606+
ExecuteField(objectType, objectValue, fieldType, fields, variableValues,
607+
fragmentVariableValues):
601608

602609
- Let {field} be the first entry in {fields}.
603610
- Let {fieldName} be the field name of {field}.
@@ -617,7 +624,8 @@ the type system to have a specific input type.
617624
At each argument position in an operation may be a literal {Value}, or a
618625
{Variable} to be provided at runtime.
619626

620-
CoerceFieldArgumentValues(objectType, field, variableValues, fragmentVariableValues):
627+
CoerceFieldArgumentValues(objectType, field, variableValues,
628+
fragmentVariableValues):
621629

622630
- Let {argumentValues} be the argument values provided in {field}.
623631
- Let {fieldName} be the name of {field}.
@@ -626,7 +634,8 @@ CoerceFieldArgumentValues(objectType, field, variableValues, fragmentVariableVal
626634
- Return {CoerceArgumentValues(argumentDefinitions, argumentValues,
627635
variableValues, fragmentVariableValues)}
628636

629-
CoerceArgumentValues(argumentDefinitions, argumentValues, variableValues, fragmentVariableValues):
637+
CoerceArgumentValues(argumentDefinitions, argumentValues, variableValues,
638+
fragmentVariableValues):
630639

631640
- For each {argumentDefinition} in {argumentDefinitions}:
632641
- Let {argumentName} be the name of {argumentDefinition}.
@@ -638,8 +647,8 @@ CoerceArgumentValues(argumentDefinitions, argumentValues, variableValues, fragme
638647
{argumentName}.
639648
- If {argumentValue} is a {Variable}:
640649
- Let {variableName} be the name of {argumentValue}.
641-
- Let {hasValue} be {true} if {fragmentVariableValues} provides a value for the name
642-
{variableName}.
650+
- Let {hasValue} be {true} if {fragmentVariableValues} provides a value for
651+
the name {variableName}.
643652
- Let {value} be the value provided in {fragmentVariableValues} for the name
644653
{variableName}.
645654
- Let {hasValue} be {true} if {variableValues} provides a value for the name

0 commit comments

Comments
 (0)