Skip to content

Commit df904d2

Browse files
committed
[RFC] GraphQL IDL additions
This adds the type definition syntax to the GraphQL specification.
1 parent bb45a6f commit df904d2

File tree

3 files changed

+284
-18
lines changed

3 files changed

+284
-18
lines changed

spec/Appendix B -- Grammar Summary.md

+51-1
Original file line numberDiff line numberDiff line change
@@ -82,13 +82,14 @@ EscapedUnicode :: /[0-9A-Fa-f]{4}/
8282
EscapedCharacter :: one of `"` \ `/` b f n r t
8383

8484

85-
## Query Document
85+
## Document
8686

8787
Document : Definition+
8888

8989
Definition :
9090
- OperationDefinition
9191
- FragmentDefinition
92+
- TypeSystemDefinition
9293

9394
OperationDefinition :
9495
- SelectionSet
@@ -169,3 +170,52 @@ NonNullType :
169170
Directives : Directive+
170171

171172
Directive : @ Name Arguments?
173+
174+
TypeSystemDefinition :
175+
- TypeDefinition
176+
- TypeExtensionDefinition
177+
- DirectiveDefinition
178+
179+
TypeDefinition :
180+
- ObjectTypeDefinition
181+
- InterfaceTypeDefinition
182+
- UnionTypeDefinition
183+
- ScalarTypeDefinition
184+
- EnumTypeDefinition
185+
- InputObjectTypeDefinition
186+
187+
ObjectTypeDefinition : type Name ImplementsInterfaces? { FieldDefinition+ }
188+
189+
ImplementsInterfaces : implements NamedType+
190+
191+
FieldDefinition : Name ArgumentsDefinition? : Type
192+
193+
ArgumentsDefinition : ( InputValueDefinition+ )
194+
195+
InputValueDefinition : Name : Type DefaultValue?
196+
197+
InterfaceTypeDefinition : interface Name { FieldDefinition+ }
198+
199+
UnionTypeDefinition : union Name = UnionMembers
200+
201+
UnionMembers :
202+
- NamedType
203+
- UnionMembers | NamedType
204+
205+
ScalarTypeDefinition : scalar Name
206+
207+
EnumTypeDefinition : enum Name { EnumValueDefinition+ }
208+
209+
EnumValueDefinition : EnumValue
210+
211+
EnumValue : Name
212+
213+
InputObjectTypeDefinition : input Name { InputValueDefinition+ }
214+
215+
TypeExtensionDefinition : extend ObjectTypeDefinition
216+
217+
DirectiveDefinition : directive @ Name ArgumentsDefinition? on DirectiveLocations
218+
219+
DirectiveLocations :
220+
- Name
221+
- DirectiveLocations | Name

spec/Section 2 -- Language.md

+231-15
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ WhiteSpace ::
4545
White space is used to improve legibility of source text and act as separation
4646
between tokens, and any amount of white space may appear before or after any
4747
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
4949
{String} or {Comment} token.
5050

5151
Note: GraphQL intentionally does not consider Unicode "Zs" category characters
@@ -62,7 +62,7 @@ LineTerminator ::
6262

6363
Like white space, line terminators are used to improve the legibility of source
6464
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
6666
terminators are not found within any other token.
6767

6868
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
8484
to but not including the line terminator.
8585

8686
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.
8989

9090

9191
### Insignificant Commas
@@ -94,7 +94,7 @@ Comma :: ,
9494

9595
Similar to white space and line terminators, commas ({`,`}) are used to improve
9696
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.
9898

9999
Non-significant comma characters ensure that the absence or presence of a comma
100100
does not meaningfully alter the interpreted syntax of the document, as this can
@@ -115,8 +115,8 @@ Token ::
115115
A GraphQL document is comprised of several kinds of indivisible lexical tokens
116116
defined here in a lexical grammar by patterns of source Unicode characters.
117117

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.
120120

121121

122122
### Ignored Tokens
@@ -152,7 +152,7 @@ lacks the punctuation often used to describe mathematical expressions.
152152

153153
Name :: /[_A-Za-z][_0-9A-Za-z]*/
154154

155-
GraphQL query documents are full of named things: operations, fields, arguments,
155+
GraphQL Documents are full of named things: operations, fields, arguments,
156156
directives, fragments, and variables. All names must follow the same
157157
grammatical form.
158158

@@ -164,28 +164,41 @@ Names in GraphQL are limited to this <acronym>ASCII</acronym> subset of possible
164164
characters to support interoperation with as many other systems as possible.
165165

166166

167-
## Query Document
167+
## Document
168168

169169
Document : Definition+
170170

171171
Definition :
172172
- OperationDefinition
173173
- FragmentDefinition
174+
- TypeDefinition
174175

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.
181176

177+
<<<<<<< HEAD
182178
If a document contains only one operation, that operation may be unnamed or
183179
represented in the shorthand form, which omits both the query keyword and
184180
operation name. Otherwise, if a GraphQL query document contains multiple
185181
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
186196
multiple operations to a GraphQL service, the name of the desired operation to
187197
be executed must also be provided.
188198

199+
GraphQL implementations which only seek to provide GraphQL query execution may
200+
omit the {TypeDefinition} rule from Definition.
201+
189202

190203
## Operations
191204

@@ -938,3 +951,206 @@ and operations.
938951

939952
As future versions of GraphQL adopts new configurable execution capabilities,
940953
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+
```

spec/Section 5 -- Validation.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -785,9 +785,9 @@ fragment inlineFragOnScalar on Dog {
785785

786786
** Explanatory Text **
787787

788-
Defined fragments must be used within a query document.
788+
Defined fragments must be used within a document.
789789

790-
For example the following is an invalid query document:
790+
For example the following is an invalid document:
791791

792792
```!graphql
793793
fragment nameFragment on Dog { # unused

0 commit comments

Comments
 (0)