Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fragment args spec suggestions #1

Open
wants to merge 6 commits into
base: fragment-args-2024-amendments
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 32 additions & 22 deletions spec/Section 5 -- Validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -474,7 +474,7 @@ unambiguous. Therefore any two field selections which might both be encountered
for the same object are only valid if they are equivalent.

During execution, the simultaneous execution of fields with the same response
name is accomplished by {MergeSelectionSets()} and {CollectFields()}.
name is accomplished by {CollectSubfields()}.

For simple hand-written GraphQL, this rule is obviously a clear developer error,
however nested fragments can make this difficult to detect manually.
Expand Down Expand Up @@ -609,8 +609,29 @@ validation fails because the fragment spread `...commandFragment(command: SIT)`
and `...commandFragment(command: DOWN)` are part of the visited selections that
will be merged.

If both of these spreads had used the same variable for the argument value, it
would be allowed as we can be sure that we'd resolve identical fields.
If both of these spreads had used the same value for the argument value, it
would be allowed as we can be sure that we would resolve identical fields.
Spreads that use different variables that would always resolve to the same value
are also valid. For example, the following is valid:

```graphql example
fragment commandFragment($command: DogCommand!) on Dog {
doesKnowCommand(dogCommand: $command)
}

fragment noConflictWhenPassedOperationCommand(
$fragmentCommand: DogCommand!
) on Dog {
...commandFragment(command: $operationCommand)
...commandFragment(command: $fragmentCommand)
}

query($operationCommand: DogCommand!) {
pet {
...noConflictWhenPassedOperationCommand(fragmentCommand: $operationCommand)
}
}
```

### Leaf Field Selections

Expand Down Expand Up @@ -1873,7 +1894,7 @@ This is because {houseTrainedQueryTwoNotDefined} does not define a variable
${atOtherHomes} but that variable is used by {isHouseTrainedFragment} which is
included in that operation.

### All Operation Variables Used
### All Variables Used

**Formal Specification**

Expand All @@ -1882,6 +1903,11 @@ included in that operation.
- Each {variable} in {variables} must be used at least once in either the
operation scope itself or any fragment transitively referenced by that
operation, excluding fragments that define the same name as an argument.
- For every {fragment} in the document:
- Let {variables} be the variables defined by that {fragment}.
- Each {variable} in {variables} must be used at least once transitively
within the fragment's selection set excluding traversal of named fragment
spreads.

**Explanatory Text**

Expand Down Expand Up @@ -1982,24 +2008,8 @@ fragment isHouseTrainedFragment on Dog {
This document is not valid because {queryWithExtraVar} defines an extraneous
variable.

### All Fragment Variables Used

**Formal Specification**

- For every {fragment} in the document:
- Let {variables} be the variables defined by that {fragment}.
- Each {variable} in {variables} must be used at least once transitively
within the fragment's selection set excluding traversal of named fragment
spreads.

**Explanatory Text**

All variables defined by a fragment must be used in that same fragment. Because
fragment-defined variables are scoped to the fragment they are defined on, if
the fragment does not use the variable, then the variable definition is
superfluous.

For example, the following is invalid:
Fragment variables must also be used within their definitions. For example, the
following is invalid:

```graphql counter-example
query queryWithFragmentArgUnused($atOtherHomes: Boolean) {
Expand Down
Loading