Skip to content

Commit ea790f2

Browse files
committed
Merge pull request #152 from facebook/fine-grain-directives
[RFC] Proposed change to directive location introspection
2 parents 2fc8ac3 + 1c38e6a commit ea790f2

File tree

4 files changed

+59
-48
lines changed

4 files changed

+59
-48
lines changed

spec/Section 2 -- Language.md

Lines changed: 0 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -928,44 +928,3 @@ and operations.
928928

929929
As future versions of GraphQL adopts new configurable execution capabilities,
930930
they may be exposed via directives.
931-
932-
#### Fragment Directives
933-
934-
Fragments may include directives to alter their behavior. At runtime, the directives provided on a fragment spread override those described on the
935-
definition.
936-
937-
For example, the following query:
938-
939-
```graphql
940-
query hasConditionalFragment($condition: Boolean) {
941-
...maybeFragment @include(if: $condition)
942-
}
943-
944-
fragment maybeFragment on Query {
945-
me {
946-
name
947-
}
948-
}
949-
```
950-
951-
Will have identical runtime behavior as
952-
953-
```graphql
954-
query hasConditionalFragment($condition: Boolean) {
955-
...maybeFragment
956-
}
957-
958-
fragment maybeFragment on Query @include(if: $condition) {
959-
me {
960-
name
961-
}
962-
}
963-
```
964-
965-
FragmentSpreadDirectives(fragmentSpread) :
966-
* Let {directives} be the set of directives on {fragmentSpread}
967-
* Let {fragmentDefinition} be the FragmentDefinition in the document named {fragmentSpread} refers to.
968-
* For each {directive} in directives on {fragmentDefinition}
969-
* If {directives} does not contain a directive named {directive}
970-
* Add {directive} into {directives}
971-
* Return {directives}

spec/Section 3 -- Type System.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -860,8 +860,9 @@ GraphQL implementations should provide the `@skip` and `@include` directives.
860860

861861
### @skip
862862

863-
The `@skip` directive may be provided for fields or fragments, and allows
864-
for conditional exclusion during execution as described by the if argument.
863+
The `@skip` directive may be provided for fields, fragment spreads, and
864+
inline fragments, and allows for conditional exclusion during execution as
865+
described by the if argument.
865866

866867
In this example `experimentalField` will be queried only if the `$someTest` is
867868
provided a `false` value.
@@ -874,8 +875,9 @@ query myQuery($someTest: Boolean) {
874875

875876
### @include
876877

877-
The `@include` directive may be provided for fields or fragments, and allows
878-
for conditional inclusion during execution as described by the if argument.
878+
The `@include` directive may be provided for fields, fragment spreads, and
879+
inline fragments, and allows for conditional inclusion during execution as
880+
described by the if argument.
879881

880882
In this example `experimentalField` will be queried only if the `$someTest` is
881883
provided a `true` value.

spec/Section 4 -- Introspection.md

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -181,10 +181,18 @@ enum __TypeKind {
181181
type __Directive {
182182
name: String!
183183
description: String
184+
locations: [__DirectiveLocation!]!
184185
args: [__InputValue!]!
185-
onOperation: Boolean!
186-
onFragment: Boolean!
187-
onField: Boolean!
186+
}
187+
188+
enum __DirectiveLocation {
189+
QUERY
190+
MUTATION
191+
SUBSCRIPTION
192+
FIELD
193+
FRAGMENT_DEFINITION
194+
FRAGMENT_SPREAD
195+
INLINE_FRAGMENT
188196
}
189197
```
190198

@@ -375,3 +383,17 @@ Fields
375383
* `defaultValue` may return a String encoding (using the GraphQL language) the
376384
default value used by this input value in the condition a value is not
377385
provided at runtime. If this input value has no default value, returns {null}.
386+
387+
388+
### The __Directive Type
389+
390+
The `__Directive` type represents a Directive that a server supports.
391+
392+
Fields
393+
394+
* `name` must return a String
395+
* `description` may return a String or {null}
396+
* `locations` returns a List of `__DirectiveLocation` representing the valid
397+
locations this directive may be placed.
398+
* `args` returns a List of `__InputValue` representing the arguments this
399+
directive accepts.

spec/Section 5 -- Validation.md

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1116,6 +1116,34 @@ For example the following query will not pass validation.
11161116
GraphQL servers define what directives they support. For each
11171117
usage of a directive, the directive must be available on that server.
11181118

1119+
1120+
### Directives Are In Valid Locations
1121+
1122+
** Formal Specification **
1123+
1124+
* For every {directive} in a document.
1125+
* Let {directiveName} be the name of {directive}.
1126+
* Let {directiveDefinition} be the directive named {directiveName}.
1127+
* Let {locations} be the valid locations for {directiveDefinition}.
1128+
* Let {adjacent} be the AST node the directive effects.
1129+
* {adjacent} must be represented by an item within {locations}.
1130+
1131+
** Explanatory Text **
1132+
1133+
GraphQL servers define what directives they support and where they support them.
1134+
For each usage of a directive, the directive must be used in a location that the
1135+
server has declared support for.
1136+
1137+
For example the following query will not pass validation because `@skip` does
1138+
not provide `QUERY` as a valid location.
1139+
1140+
```!graphql
1141+
query @skip(if: $foo) {
1142+
field
1143+
}
1144+
```
1145+
1146+
11191147
## Variables
11201148

11211149
### Variable Uniqueness

0 commit comments

Comments
 (0)