diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md index 845667211..fc1a68e03 100644 --- a/spec/Section 2 -- Language.md +++ b/spec/Section 2 -- Language.md @@ -909,44 +909,3 @@ and operations. As future versions of GraphQL adopts new configurable execution capabilities, they may be exposed via directives. - -#### Fragment Directives - -Fragments may include directives to alter their behavior. At runtime, the directives provided on a fragment spread override those described on the -definition. - -For example, the following query: - -```graphql -query hasConditionalFragment($condition: Boolean) { - ...maybeFragment @include(if: $condition) -} - -fragment maybeFragment on Query { - me { - name - } -} -``` - -Will have identical runtime behavior as - -```graphql -query hasConditionalFragment($condition: Boolean) { - ...maybeFragment -} - -fragment maybeFragment on Query @include(if: $condition) { - me { - name - } -} -``` - -FragmentSpreadDirectives(fragmentSpread) : - * Let {directives} be the set of directives on {fragmentSpread} - * Let {fragmentDefinition} be the FragmentDefinition in the document named {fragmentSpread} refers to. - * For each {directive} in directives on {fragmentDefinition} - * If {directives} does not contain a directive named {directive} - * Add {directive} into {directives} - * Return {directives} diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 37b032ade..4056171cc 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -767,8 +767,9 @@ GraphQL implementations should provide the `@skip` and `@include` directives. ### @skip -The `@skip` directive may be provided for fields or fragments, and allows -for conditional exclusion during execution as described by the if argument. +The `@skip` directive may be provided for fields, fragment spreads, and +inline fragments, and allows for conditional exclusion during execution as +described by the if argument. In this example `experimentalField` will be queried only if the `$someTest` is provided a `false` value. @@ -781,8 +782,9 @@ query myQuery($someTest: Boolean) { ### @include -The `@include` directive may be provided for fields or fragments, and allows -for conditional inclusion during execution as described by the if argument. +The `@include` directive may be provided for fields, fragment spreads, and +inline fragments, and allows for conditional inclusion during execution as +described by the if argument. In this example `experimentalField` will be queried only if the `$someTest` is provided a `true` value. diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index b63255842..f6c116c91 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -181,10 +181,18 @@ enum __TypeKind { type __Directive { name: String! description: String + locations: [__DirectiveLocation!]! args: [__InputValue!]! - onOperation: Boolean! - onFragment: Boolean! - onField: Boolean! +} + +enum __DirectiveLocation { + QUERY + MUTATION + SUBSCRIPTION + FIELD + FRAGMENT_DEFINITION + FRAGMENT_SPREAD + INLINE_FRAGMENT } ``` @@ -375,3 +383,17 @@ Fields * `defaultValue` may return a String encoding (using the GraphQL language) the default value used by this input value in the condition a value is not provided at runtime. If this input value has no default value, returns {null}. + + +### The __Directive Type + +The `__Directive` type represents a Directive that a server supports. + +Fields + +* `name` must return a String +* `description` may return a String or {null} +* `locations` returns a List of `__DirectiveLocation` representing the valid + locations this directive may be placed. +* `args` returns a List of `__InputValue` representing the arguments this + directive accepts. diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md index f9d150d17..2d7a89cd1 100644 --- a/spec/Section 5 -- Validation.md +++ b/spec/Section 5 -- Validation.md @@ -1100,6 +1100,34 @@ For example the following query will not pass validation. GraphQL servers define what directives they support. For each usage of a directive, the directive must be available on that server. + +### Directives Are In Valid Locations + +** Formal Specification ** + + * For every {directive} in a document. + * Let {directiveName} be the name of {directive}. + * Let {directiveDefinition} be the directive named {directiveName}. + * Let {locations} be the valid locations for {directiveDefinition}. + * Let {adjacent} be the AST node the directive effects. + * {adjacent} must be represented by an item within {locations}. + +** Explanatory Text ** + +GraphQL servers define what directives they support and where they support them. +For each usage of a directive, the directive must be used in a location that the +server has declared support for. + +For example the following query will not pass validation because `@skip` does +not provide `QUERY` as a valid location. + +```!graphql +query @skip(if: $foo) { + field +} +``` + + ## Variables ### Variable Uniqueness