Fragment arguments - needs champion - #1224
Open
benjie wants to merge 54 commits into
Open
Conversation
Co-authored-by: Matt Mahoney <mahoney.mattj@gmail.com>
Co-authored-by: Benjie <benjie@jemjie.com>
Co-authored-by: Benjie <benjie@jemjie.com>
Co-authored-by: Benjie <benjie@jemjie.com>
Co-authored-by: Benjie <benjie@jemjie.com>
Co-authored-by: Benjie <benjie@jemjie.com>
Co-authored-by: Benjie <benjie@jemjie.com>
Fragment arguments editorial
benjie
added
👻 Needs Champion
✅ Deploy Preview for graphql-spec-draft ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
yaacovCR
added a commit
to yaacovCR/graphql-js
that referenced
this pull request
Jul 20, 2026
The initial v17 release included validation of fragment arguments using an earlier, rejected version of the field selection merging rules. This PR updates fragment arguments validation to conform to the current spec proposal. The proposal intentionally requires variables in otherwise identical arguments to refer to the same variable definition. Following argument values through fragment spreads could allow more documents, but it makes the logic for determining whether arguments are the same significantly more complex. The current fragment arguments proposal proposal takes the conservative approach of rejecting these cases. References: - Current fragment arguments proposal: graphql/graphql-spec#1224 - Earlier (now-closed) fragment arguments proposal: graphql/graphql-spec#1081 - Benjie's rationale for the conservative validation rule: graphql/graphql-spec#1081 (comment) - Benjie's follow-up PR updating the proposal: JoviDeCroock/graphql-spec#2 - Proposal commit requiring references to the same variable definition: graphql/graphql-spec@6659416 - Initial GraphQL.js fragment arguments implementation: graphql#4015
yaacovCR
added a commit
to yaacovCR/graphql-js
that referenced
this pull request
Jul 20, 2026
The initial v17 release included validation of fragment arguments using an earlier, rejected version of the field selection merging rules. This PR updates fragment arguments validation to the current spec proposal.
The current spec proposal intentionally requires variables in otherwise identical arguments to refer to the same variable definition. Following argument values through fragment spreads could allow more documents, but it makes the logic for determining whether arguments are the same significantly more complex. The current fragment arguments proposal takes the conservative approach of rejecting these cases.
For example, these fields appear to use the same operation variable:
```graphql
query Example($size: Int!) {
user {
image(size: $size)
...Image(size: $size)
}
}
fragment Image($size: Int!) on User {
image(size: $size)
}
```
The first field uses the operation variable, while the field in `Image` uses the fragment variable. Treating them as equal requires resolving the spread argument before comparing the fields.
A literal may also match a fragment variable default:
```graphql
query Example {
user {
image(size: 10)
...Image
}
}
fragment Image($size: Int = 10) on User {
image(size: $size)
}
```
Treating these fields as equal requires applying the omitted fragment argument default during field selection merging.
Bindings may also pass through several fragments:
```graphql
query Example($size: Int!) {
user {
image(size: $size)
...Outer(size: $size)
}
}
fragment Outer($size: Int!) on User {
...Image(size: $size)
}
fragment Image($size: Int!) on User {
image(size: $size)
}
```
Treating these fields as equal requires following the operation variable through both fragment variable definitions.
Allowing these cases means a fragment cannot be checked on its own. The validator must carry variable bindings into each spread, apply defaults, follow bindings through nested fragments, cache the same fragment separately for different bindings, and handle cycles while doing so. Whether two arguments are the same then depends on the full path to the fragment.
Requiring the same variable definition keeps the check local. Variables are compared by their definition rather than by tracing the values passed to them. The stricter rule can also be relaxed later without invalidating documents that are already valid, but v17 incorrectly released the more lenient rule despite the currently stricter stance within the specification.
References:
- Current fragment arguments proposal: graphql/graphql-spec#1224
- Earlier (now-closed) fragment arguments proposal: graphql/graphql-spec#1081
- Benjie's rationale for the conservative validation rule: graphql/graphql-spec#1081 (comment)
- Benjie's follow-up PR updating the proposal: JoviDeCroock/graphql-spec#2
- Proposal commit requiring references to the same variable definition: graphql/graphql-spec@6659416
- Initial GraphQL.js fragment arguments implementation: graphql#4015
yaacovCR
added a commit
to graphql/graphql-js
that referenced
this pull request
Jul 20, 2026
…#4839) The initial v17 release included validation of fragment arguments using an earlier, rejected version of the field selection merging rules. This PR updates fragment arguments validation to the current spec proposal. The current spec proposal intentionally requires variables in otherwise identical arguments to refer to the same variable definition. Following argument values through fragment spreads could allow more documents, but it makes the logic for determining whether arguments are the same significantly more complex. The current fragment arguments proposal takes the conservative approach of rejecting these cases. For example, these fields appear to use the same operation variable: ```graphql query Example($size: Int!) { user { image(size: $size) ...Image(size: $size) } } fragment Image($size: Int!) on User { image(size: $size) } ``` The first field uses the operation variable, while the field in `Image` uses the fragment variable. Treating them as equal requires resolving the spread argument before comparing the fields. A literal may also match a fragment variable default: ```graphql query Example { user { image(size: 10) ...Image } } fragment Image($size: Int = 10) on User { image(size: $size) } ``` Treating these fields as equal requires applying the omitted fragment argument default during field selection merging. Bindings may also pass through several fragments: ```graphql query Example($size: Int!) { user { image(size: $size) ...Outer(size: $size) } } fragment Outer($size: Int!) on User { ...Image(size: $size) } fragment Image($size: Int!) on User { image(size: $size) } ``` Treating these fields as equal requires following the operation variable through both fragment variable definitions. Allowing these cases means a fragment cannot be checked on its own. The validator must carry variable bindings into each spread, apply defaults, follow bindings through nested fragments, cache the same fragment separately for different bindings, and handle cycles while doing so. Whether two arguments are the same then depends on the full path to the fragment. Requiring the same variable definition keeps the check local. Variables are compared by their definition rather than by tracing the values passed to them. The stricter rule can also be relaxed later without invalidating documents that are already valid, but v17 incorrectly released the more lenient rule despite the currently stricter stance within the specification. References: - Current fragment arguments proposal: graphql/graphql-spec#1224 - Earlier (now-closed) fragment arguments proposal: graphql/graphql-spec#1081 - Benjie's rationale for the conservative validation rule: graphql/graphql-spec#1081 (comment) - Benjie's follow-up PR updating the proposal: JoviDeCroock/graphql-spec#2 - Proposal commit requiring references to the same variable definition: graphql/graphql-spec@6659416 - Initial GraphQL.js fragment arguments implementation: #4015
yaacovCR
added a commit
to yaacovCR/graphql-js
that referenced
this pull request
Jul 21, 2026
Bind fragment variables as compact scopes on the same selection-set graph, reject incompatible spread arguments before fieldless-root canonicalization, and share alpha-equivalent bound proofs. Keep charging unweighted selection scans, field-set expansions, and new proofs as work. Replacing the fallback pairwise fragment comparisons with grouped bound proofs permits lowering the configurable default safety budget from 5,000 to 2,000 units while accepting substantially larger fragment-spread sets. This builds on [the fragment arguments proposal](graphql/graphql-spec#1224) and [its GraphQL.js implementation](graphql#4015).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See #1081 for more details