Fragment arguments/variables (syntax/validation/execution)

At a glance

• Identifier: #1081
• Stage: RFC 2 / Draft
• Champion: @JoviDeCroock
• Latest activity: Spec PR closed on 2026-03-08
• Spec PR: https://github.com/graphql/graphql-spec/pull/1081
• Related:
  • #1010
  • #204

Spec PR description

This spec contains amendments to https://github.com/graphql/graphql-spec/pull/1010, a diffed view is available at https://github.com/mjmahone/graphql-spec/pull/3.

These amendments are made from comments on the implementation PR and alterations from the new implementation

• Changing fragment-key to just be fragment-name https://github.com/graphql/graphql-js/pull/3835#discussion_r1101825832
• Removing the substitution logic and going closer to the coerce logic we use in the general flow

In general the biggest changes are that we introduce fragmentVariableValues which will be on the groupedFieldSet, these are derived from the arguments in scope of the fragmentDefinition where this field is used.

We introduce localFragmentVariables which as we are traversing down fragment-spreads are a coerced set of variables i.e.

query($b: String!, $c: String!) {
  field3(b: $b) ## uses b from variable-values
  ...A(a: "A", b: "B")
}

fragment A($a: String!, $b: String!) on X {
  field(a: $a) ## uses $a from localVariableValues
  field2(c: $c) ## we have access to variableValues so we take c from there
  ...B(b: $b) ## uses $b from localVariableValues
}

fragment B($b: String!) on X {
  ## This fragment has access to $b and $c but not to $a
  field4(b: $b) ## uses $b from localVariableValues
}

Last but not least we introduce getArgumentValuesFromSpread which looks at the spread and fragment-definition and establishes a coerced set of localVariableValues.

• Fixes https://github.com/graphql/graphql-spec/issues/204