{operation,fragment}-defined variable -> {operation,fragment} variable

Author: benjie

spec/Section 2 -- Language.md

@@ -1283,20 +1283,28 @@ size `60`:
 
 **Variable Use Within Fragments**
 
-Variables can be used within fragments. Operation-defined variables have global
-scope within a given operation. Fragment-defined variables have local scope
-within the fragment definition in which they are defined. A variable used within
-a fragment must either be declared in each top-level operation that transitively
-consumes that fragment, or by that same fragment as a fragment variable
-definition. If a variable referenced in a fragment is included by an operation
-where neither the fragment nor the operation defines that variable, that
-operation is invalid (see
-[All Variable Uses Defined](#sec-All-Variable-Uses-Defined)).
+Variables can be used within fragments.
+
+:: An _operation variable_ is a variable defined on an operation. An operation
+variable has global scope within that operation, including within any fragments
+that operation transitively consumes.
+
+:: 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).
+
+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 fragments to be
-reused while enabling the caller to specify the fragment's behavior.
+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:
@@ -1321,8 +1329,8 @@ fragment dynamicProfilePic($size: Int! = 50) on User {
 In this case the `user` will have a larger `profilePic` than those found in the
 list of `friends`.
 
-A fragment-defined variable is scoped to the fragment that defines it.
-Fragment-defined variables are allowed to shadow operation-defined variables.
+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!) {
@@ -1345,9 +1353,9 @@ fragment dynamicProfilePic($size: Int!) on User {
 
 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 operation-defined
-variable, while `dynamicProfilePic` uses the value passed in via the fragment
-spread's `size` argument.
+this case, the fragment `variableProfilePic` uses the _operation variable_,
+while `dynamicProfilePic` uses the value passed in via the fragment spread's
+`size` argument.
 
 ## Type References
 

spec/Section 5 -- Validation.md

@@ -1853,12 +1853,12 @@ fragment HouseTrainedDog($atOtherHomes: Boolean) on Dog {
 }
 ```
 
-Fragment-defined variables are scoped locally to the fragment that defines them,
-and override any operation-defined variable values, so there is never ambiguity
-about which value to use. In this case, the value of the argument `atOtherHomes`
-within `HouseTrainedFragment` will be the operation-set value, and within
-`HouseTrainedDog` will default to being unset (unless a default-value applies),
-as the argument is not set by the fragment spread in the query `C`.
+A _fragment variable_ is scoped locally to the fragment that defines it, and
+overrides the _operation variable_ of the same name, if any, so there is never
+ambiguity about which value to use. In this case, the value of the argument
+`atOtherHomes` within `HouseTrainedFragment` will be the operation-set value,
+and within `HouseTrainedDog` will default to being unset (unless a default-value
+applies), as the argument is not set by the fragment spread in the query `C`.
 
 ### Variables Are Input Types
 
@@ -1938,10 +1938,10 @@ query takesCatOrDog($catOrDog: CatOrDog) {
 
 **Explanatory Text**
 
-Operation-defined Variables are scoped on a per-operation basis, while
-Fragment-defined Variables are scoped locally to the fragment. That means that
-any variable used within the context of an operation must either be defined at
-the top level of that operation or on the fragment that uses that variable.
+An _operation variable_ is scoped on a per-operation basis, while a _fragment
+variable_ is scoped locally to the fragment. That means that any variable used
+within the context of an operation must either be defined at the top level of
+that operation or on the fragment that uses that variable.
 
 For example:
 
@@ -2134,7 +2134,7 @@ fragment isHouseTrainedWithoutVariableFragment on Dog {
 ```
 
 Fragment arguments can shadow operation variables: fragments that use an
-argument are not using the operation-defined variable of the same name.
+argument are not using the _operation variable_ of the same name.
 
 As such, it would be invalid if the operation defined a variable and variables
 of that name were used exclusively inside fragments that define a variable with
@@ -2154,8 +2154,8 @@ fragment shadowedVariableFragment($atOtherHomes: Boolean) on Dog {
 
 because
 {$atOtherHomes} is only referenced in a fragment that defines it as a
-locally scoped argument, the operation-defined {$atOtherHomes}
-variable is never used.
+locally scoped argument, the _operation variable_ {$atOtherHomes}
+is never used.
 
 All operations in a document must use all of their variables.