Fragment arguments/variables (syntax/validation/execution)

spec/Appendix C -- Grammar Summary.md

@@ -172,12 +172,12 @@ Arguments[Const] : ( Argument[?Const]+ )
 
 Argument[Const] : Name : Value[?Const]
 
-FragmentSpread : ... FragmentName Directives?
+FragmentSpread : ... FragmentName Arguments? Directives?
 
 InlineFragment : ... TypeCondition? Directives? SelectionSet
 
-FragmentDefinition : Description? fragment FragmentName TypeCondition
-Directives? SelectionSet
+FragmentDefinition : Description? fragment FragmentName VariablesDefinition?
+TypeCondition Directives? SelectionSet
 
 FragmentName : Name but not `on`
 

spec/Section 2 -- Language.md

@@ -578,10 +578,10 @@ which returns the result:
 
 ## Fragments
 
-FragmentSpread : ... FragmentName Directives?
+FragmentSpread : ... FragmentName Arguments? Directives?
 
-FragmentDefinition : Description? fragment FragmentName TypeCondition
-Directives? SelectionSet
+FragmentDefinition : Description? fragment FragmentName VariablesDefinition?
+TypeCondition Directives? SelectionSet
 
 FragmentName : Name but not `on`
 
@@ -1251,10 +1251,15 @@ avoiding costly string building in clients at runtime.
 If not defined as constant (for example, in {DefaultValue}), a {Variable} can be
 supplied for an input value.
 
-Variables must be defined at the top of an operation and are in scope throughout
-the execution of that operation. Values for those variables are provided to a
-GraphQL service as part of a request so they may be substituted in during
-execution.
+:: An _operation variable_ is a variable defined at the top of an operation. An
+operation variable is in scope throughout the execution of that operation.
+Values for operation variables are provided to a GraphQL service as part of a
+request so they may be substituted in during execution.
+
+:: A _fragment variable_ is a variable defined on a fragment. A fragment
+variable is locally scoped, it may only be referenced within that fragment
+(non-transitively). Values for fragment variables are provided to fragment
+spreads.
 
 In this example, we want to fetch a profile picture size based on the size of a
 particular device:
@@ -1283,13 +1288,73 @@ size `60`:
 
 **Variable Use Within Fragments**
 
-Variables can be used within fragments. Variables have global scope with a given
-operation, so a variable used within a fragment must be declared in any
-top-level operation that transitively consumes that fragment. If a variable is
-referenced in a fragment and is included by an operation that does not define
-that variable, that operation is invalid (see
+Variables can be used within fragments. An _operation variable_ has global scope
+within that operation, including within any fragments that operation
+transitively consumes. A variable used within a fragment must either be defined
+by that fragment, or must be declared in each top-level operation that
+transitively consumes that fragment. If a variable referenced in a fragment is
+defined in both the fragment and the operation, the fragment definition will be
+used. If a variable is referenced in a fragment and is not defined by that
+fragment, then any operation that transitively references the fragment and does
+not define that variable is invalid (see
 [All Variable Uses Defined](#sec-All-Variable-Uses-Defined)).
 
+## Fragment Variable Definitions
+
+Fragments may define locally scoped variables. This allows the caller to specify
+the fragment's behavior.
+
+For example, the profile picture may need to be a different size depending on
+the parent context:
+
+```graphql example
+query userAndFriends {
+  user(id: 4) {
+    ...dynamicProfilePic(size: 100)
+    friends(first: 10) {
+      id
+      name
+      ...dynamicProfilePic
+    }
+  }
+}
+
+fragment dynamicProfilePic($size: Int! = 50) on User {
+  profilePic(size: $size)
+}
+```
+
+In this case the `user` will have a larger `profilePic` than those found in the
+list of `friends`.
+
+A _fragment variable_ is scoped to the fragment that defines it. A fragment
+variable may shadow an _operation variable_.
+
+```graphql example
+query withShadowedVariables($size: Int!) {
+  user(id: 4) {
+    ...variableProfilePic
+  }
+  secondUser: user(id: 5) {
+    ...dynamicProfilePic(size: 10)
+  }
+}
+
+fragment variableProfilePic on User {
+  ...dynamicProfilePic(size: $size)
+}
+
+fragment dynamicProfilePic($size: Int!) on User {
+  profilePic(size: $size)
+}
+```
+
+In the example above, the profilePic for `user` will be determined by the
+variables set by the operation, while `secondUser` will always have a
+`profilePic` of size `10`. In this case, the fragment `variableProfilePic` uses
+the value of the _operation variable_, while `dynamicProfilePic` uses the value
+of the _fragment variable_ passed in via the fragment spread's `size` argument.
+
 ## Type References
 
 Type :