All Variables Used

Formal Specification

• For every operation in the document.
• Let variables be the variables defined by 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.

Explanatory Text

All variables defined by an operation must be used in that operation or a fragment transitively included by that operation. Unused variables cause a validation error.

For example the following is invalid:

query variableUnused($atOtherHomes: Boolean) {
  dog {
    isHousetrained
  }
}

because $atOtherHomesis not referenced.

These rules apply to transitive fragment spreads as well:

query variableUsedInFragment($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

The above is valid since $atOtherHomesis used inisHousetrainedFragmentwhich is included byvariableUsedInFragment.

If that fragment did not have a reference to $atOtherHomesit would be not valid:

query variableNotUsedWithinFragment($atOtherHomes: Boolean) {
  ...isHousetrainedWithoutVariableFragment
}

fragment isHousetrainedWithoutVariableFragment on Dog {
  isHousetrained
}

All operations in a document must use all of their variables.

As a result, the following document does not validate.

query queryWithUsedVar($atOtherHomes: Boolean) {
  dog {
    ...isHousetrainedFragment
  }
}

query queryWithExtraVar($atOtherHomes: Boolean, $extra: Int) {
  dog {
    ...isHousetrainedFragment
  }
}

fragment isHousetrainedFragment on Dog {
  isHousetrained(atOtherHomes: $atOtherHomes)
}

This document is not valid becausequeryWithExtraVardefines an extraneous variable.