@@ -45,7 +45,7 @@ WhiteSpace ::
45
45
White space is used to improve legibility of source text and act as separation
46
46
between tokens, and any amount of white space may appear before or after any
47
47
token. White space between tokens is not significant to the semantic meaning of
48
- a GraphQL query document , however white space characters may appear within a
48
+ a GraphQL Document , however white space characters may appear within a
49
49
{String} or {Comment} token.
50
50
51
51
Note: GraphQL intentionally does not consider Unicode "Zs" category characters
@@ -62,7 +62,7 @@ LineTerminator ::
62
62
63
63
Like white space, line terminators are used to improve the legibility of source
64
64
text, any amount may appear before or after any other token and have no
65
- significance to the semantic meaning of a GraphQL query document . Line
65
+ significance to the semantic meaning of a GraphQL Document . Line
66
66
terminators are not found within any other token.
67
67
68
68
Note: Any error reporting which provide the line number in the source of the
@@ -84,8 +84,8 @@ comment always consists of all code points starting with the {`#`} character up
84
84
to but not including the line terminator.
85
85
86
86
Comments behave like white space and may appear after any token, or before a
87
- line terminator, and have no significance to the semantic meaning of a GraphQL
88
- query document .
87
+ line terminator, and have no significance to the semantic meaning of a
88
+ GraphQL Document .
89
89
90
90
91
91
### Insignificant Commas
@@ -94,7 +94,7 @@ Comma :: ,
94
94
95
95
Similar to white space and line terminators, commas ({` , ` }) are used to improve
96
96
the legibility of source text and separate lexical tokens but are otherwise
97
- syntactically and semantically insignificant within GraphQL query documents .
97
+ syntactically and semantically insignificant within GraphQL Documents .
98
98
99
99
Non-significant comma characters ensure that the absence or presence of a comma
100
100
does not meaningfully alter the interpreted syntax of the document, as this can
@@ -115,8 +115,8 @@ Token ::
115
115
A GraphQL document is comprised of several kinds of indivisible lexical tokens
116
116
defined here in a lexical grammar by patterns of source Unicode characters.
117
117
118
- Tokens are later used as terminal symbols in a GraphQL query document syntactic
119
- grammars.
118
+ Tokens are later used as terminal symbols in a GraphQL Document
119
+ syntactic grammars.
120
120
121
121
122
122
### Ignored Tokens
@@ -152,7 +152,7 @@ lacks the punctuation often used to describe mathematical expressions.
152
152
153
153
Name :: /[ _ A-Za-z] [ _0-9A-Za-z ] * /
154
154
155
- GraphQL query documents are full of named things: operations, fields, arguments,
155
+ GraphQL Documents are full of named things: operations, fields, arguments,
156
156
directives, fragments, and variables. All names must follow the same
157
157
grammatical form.
158
158
@@ -164,28 +164,41 @@ Names in GraphQL are limited to this <acronym>ASCII</acronym> subset of possible
164
164
characters to support interoperation with as many other systems as possible.
165
165
166
166
167
- ## Query Document
167
+ ## Document
168
168
169
169
Document : Definition+
170
170
171
171
Definition :
172
172
- OperationDefinition
173
173
- FragmentDefinition
174
+ - TypeDefinition
174
175
175
- A GraphQL query document describes a complete file or request string received by
176
- a GraphQL service. A document contains multiple definitions of Operations and
177
- Fragments. GraphQL query documents are only executable by a server if they
178
- contain an operation. However documents which do not contain operations may
179
- still be parsed and validated to allow client to represent a single request
180
- across many documents.
181
176
177
+ <<<<<<< HEAD
182
178
If a document contains only one operation, that operation may be unnamed or
183
179
represented in the shorthand form, which omits both the query keyword and
184
180
operation name. Otherwise, if a GraphQL query document contains multiple
185
181
operations, each operation must be named. When submitting a query document with
182
+ =======
183
+ A GraphQL Document describes a complete file or request string operated on
184
+ by a GraphQL service or client tool. A document contains multiple definitions of
185
+ Operations and Fragments, and if consumed by a client tool may also include Type
186
+ Definitions. GraphQL Documents are only executable by a server if they
187
+ contain an Operation but do not contain a Type Definition. However documents
188
+ which do not contain Operations may still be parsed and validated to allow
189
+ client tools to represent a single request across many documents.
190
+
191
+ If a Document contains only one query operation, that operation may be
192
+ represented in the shorthand form, which omits the query keyword and
193
+ operation name. Otherwise, if a GraphQL Document contains multiple
194
+ operations, each operation must be named. When submitting a Document with
195
+ >>>>>>> 2ff83c4... [ RFC] GraphQL IDL additions
186
196
multiple operations to a GraphQL service, the name of the desired operation to
187
197
be executed must also be provided.
188
198
199
+ GraphQL implementations which only seek to provide GraphQL query execution may
200
+ omit the {TypeDefinition} rule from Definition.
201
+
189
202
190
203
## Operations
191
204
@@ -938,3 +951,206 @@ and operations.
938
951
939
952
As future versions of GraphQL adopts new configurable execution capabilities,
940
953
they may be exposed via directives.
954
+
955
+
956
+ ### Type System Definition
957
+
958
+ TypeSystemDefinition :
959
+ - TypeDefinition
960
+ - TypeExtensionDefinition
961
+ - DirectiveDefinition
962
+
963
+ The GraphQL language also includes an
964
+ [ IDL] ( https://en.wikipedia.org/wiki/Interface_description_language ) used to
965
+ describe a GraphQL service's Type System. Tools may use these definitions to
966
+ provide various utilities such as client code generation or
967
+ service boot-strapping.
968
+
969
+ A GraphQL Document which contains type system definitions must not be executed;
970
+ GraphQL execution services which receive a GraphQL Document containing type
971
+ system definitions should return a descriptive error.
972
+
973
+ Note: This IDL is used throughout the remainder of this specification document
974
+ when illustrating example type systems.
975
+
976
+
977
+ #### Type Definition
978
+
979
+ TypeDefinition :
980
+ - ObjectTypeDefinition
981
+ - InterfaceTypeDefinition
982
+ - UnionTypeDefinition
983
+ - ScalarTypeDefinition
984
+ - EnumTypeDefinition
985
+ - InputObjectTypeDefinition
986
+
987
+ A GraphQL Type System is defined by many different kinds of types.
988
+
989
+
990
+ #### Object
991
+
992
+ ObjectTypeDefinition : type Name ImplementsInterfaces? { FieldDefinition+ }
993
+
994
+ ImplementsInterfaces : implements NamedType+
995
+
996
+ FieldDefinition : Name ArgumentsDefinition? : Type
997
+
998
+ ArgumentsDefinition : ( InputValueDefinition+ )
999
+
1000
+ InputValueDefinition : Name : Type DefaultValue?
1001
+
1002
+ Object types represent a list of named fields, each of which yield a value of a
1003
+ specific type. Each field itself may accept a list of named arguments.
1004
+
1005
+ Objects may implement Interface types. When implementing an Interface type, the
1006
+ Object type must supply all fields defined by the Interface.
1007
+
1008
+ In this example, a Object type called ` TodoItem ` is defined:
1009
+
1010
+ ``` graphql
1011
+ type TodoItem implements Node {
1012
+ id : ID
1013
+ title : String
1014
+ isCompleted : Boolean
1015
+ }
1016
+ ```
1017
+
1018
+ #### Interface
1019
+
1020
+ InterfaceTypeDefinition : interface Name { FieldDefinition+ }
1021
+
1022
+ Interface types , similarly to Object types represent a list of named fields .
1023
+ Interface types are used as the type of a field when one of many possible Object
1024
+ types may yielded during execution , but some fields are guaranteed . An Object
1025
+ type is a possible type of an Interface when it both declares that it implements
1026
+ that Interface as well as includes all defined fields .
1027
+
1028
+ In this example , an Interface type called `Node ` is defined :
1029
+
1030
+ ```graphql
1031
+ interface Node {
1032
+ id : ID
1033
+ }
1034
+ ```
1035
+
1036
+ #### Union
1037
+
1038
+ UnionTypeDefinition : union Name = UnionMembers
1039
+
1040
+ UnionMembers :
1041
+ - NamedType
1042
+ - UnionMembers | NamedType
1043
+
1044
+ Union types represent a list of named Object types . Union types are used as the
1045
+ type of a field when one of many possible Object types may yielded during
1046
+ execution , and no fields are guaranteed . An Object type is a possible type of a
1047
+ Union when it is declared by the Union .
1048
+
1049
+ In this example , a Union type called `Actor ` is defined :
1050
+
1051
+ ```graphql
1052
+ union Actor = User | Business
1053
+ ```
1054
+
1055
+ #### Scalar
1056
+
1057
+ ScalarTypeDefinition : scalar Name
1058
+
1059
+ Scalar types represent leaf values in a GraphQL type system . While this GraphQL
1060
+ specification describes a set of Scalar types which all GraphQL services must
1061
+ supply , custom Scalar types may be supplied by a GraphQL service . Typically , the
1062
+ set of Scalar types described in this specification are omitted from documents
1063
+ which describe a schema for brevity.
1064
+
1065
+ In this example, a Scalar type called `DateTime` is defined:
1066
+
1067
+ ```graphql
1068
+ scalar DateTime
1069
+ ```
1070
+
1071
+ #### Enum
1072
+
1073
+ EnumTypeDefinition : enum Name { EnumValueDefinition+ }
1074
+
1075
+ EnumValueDefinition : EnumValue
1076
+
1077
+ EnumValue : Name
1078
+
1079
+ Enum types , like Scalar types , also represent leaf values in a GraphQL type
1080
+ system . However Enum types describe the set of legal values .
1081
+
1082
+ In this example , an Enum type called `Direction ` is defined :
1083
+
1084
+ ```graphql
1085
+ enum Direction {
1086
+ NORTH
1087
+ EAST
1088
+ SOUTH
1089
+ WEST
1090
+ }
1091
+ ```
1092
+
1093
+ #### Input Object
1094
+
1095
+ InputObjectTypeDefinition : input Name { InputValueDefinition+ }
1096
+
1097
+ Input Object types represent complex input values which may be provided as an
1098
+ field argument. Input Object types cannot be the return type of an Object or
1099
+ Interface field.
1100
+
1101
+ In this example, an Input Object called ` Point2D ` is defined:
1102
+
1103
+ ``` graphql
1104
+ input Point2D {
1105
+ x : Float
1106
+ y : Float
1107
+ }
1108
+ ```
1109
+
1110
+ #### Type Extension
1111
+
1112
+ TypeExtensionDefinition : extend ObjectTypeDefinition
1113
+
1114
+ Type extensions may be used by client -side tools in order to represent a
1115
+ GraphQL type system which has been extended from the type system exposed via
1116
+ introspection by a GraphQL service , for example to represent fields which a
1117
+ client of GraphQL uses locally , but is not provided by a GraphQL service .
1118
+
1119
+ Any fields or interfaces provided by the extension must not already exist on the
1120
+ Object type .
1121
+
1122
+ In this example , a client only field is added to a `Story ` type :
1123
+
1124
+ ```graphql
1125
+ extend type Story {
1126
+ isHiddenLocally : Boolean
1127
+ }
1128
+ ```
1129
+
1130
+ #### Directive Definition
1131
+
1132
+ DirectiveDefinition : directive @ Name ArgumentsDefinition ? on DirectiveLocations
1133
+
1134
+ DirectiveLocations :
1135
+ - Name
1136
+ - DirectiveLocations | Name
1137
+
1138
+ A GraphQL Type System often also includes directives which may be used to
1139
+ annotate various nodes in a GraphQL document as an indicator that they should be
1140
+ evaluated differently by a validator , executor , or client tool such as a
1141
+ code generator .
1142
+
1143
+ Since the validation of a GraphQL document includes ensuring that any directives
1144
+ used are defined and used correctly , defining a directive allows for a validator
1145
+ to be aware of all possible validation rules .
1146
+
1147
+ In this example , a directive is defined which can be used to annotate a
1148
+ fragment definition :
1149
+
1150
+ ```
1151
+ directive @someAnnotation on FRAGMENT_DEFINITION
1152
+
1153
+ fragment SomeFragment on SomeType @someAnnotation {
1154
+ someField
1155
+ }
1156
+ ```
0 commit comments