diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index 18d33605d..c0fa0b0d7 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -1242,6 +1242,45 @@ query @skip(if: $foo) { ``` +### Directives Are Unique Per Location + +** Formal Specification ** + + * For every {location} in the document for which Directives can apply: + * Let {directives} be the set of Directives which apply to {location}. + * For each {directive} in {directives}: + * Let {directiveName} be the name of {directive}. + * Let {namedDirectives} be the set of all Directives named {directiveName} + in {directives}. + * {namedDirectives} must be a set of one. + +** Explanatory Text ** + +Directives are used to describe some metadata or behavioral change on the +definition they apply to. When more than one directive of the same name is used, +the expected metadata or behavior becomes ambiguous, therefore only one of each +directive is allowed per location. + +For example, the following query will not pass validation because `@skip` has +been used twice for the same field: + +```!graphql +query ($foo: Boolean = true, $bar: Boolean = false) { + field @skip(if: $foo) @skip(if: $bar) +} +``` + +However this example is valid because `@skip` has been used only once per +location, despite being used twice in the query: + +```graphql +query ($foo: Boolean = true, $bar: Boolean = false) { + fieldA @skip(if: $foo) + fieldB @skip(if: $bar) +} +``` + + ## Variables ### Variable Uniqueness