@@ -264,32 +264,43 @@ TypeDefinition :
264
264
- EnumTypeDefinition
265
265
- InputObjectTypeDefinition
266
266
267
- The fundamental unit of any GraphQL Schema is the type. There are six kinds of
267
+ The fundamental unit of any GraphQL schema is the type. There are six kinds of
268
268
named type definitions in GraphQL, and two wrapping types.
269
269
270
- The most basic type is a ` Scalar ` . A scalar represents a primitive value, like a
271
- string or an integer. Oftentimes, the possible responses for a scalar field are
272
- enumerable. GraphQL offers an ` Enum ` type in those cases, where the type
273
- specifies the space of valid responses.
270
+ :: A _ leaf type_ is a kind of type representing a primitive value which cannot
271
+ be further selected and thus form the leaves in a response tree. GraphQL
272
+ provides two kinds of leaf types: ` Scalar ` and ` Enum ` .
274
273
275
- Scalars and Enums form the leaves in response trees; the intermediate levels are
276
- ` Object ` types, which define a set of fields, where each field is another type
277
- in the system, allowing the definition of arbitrary type hierarchies.
274
+ A ` Scalar ` represents a primitive scalar value, such as a string or number.
275
+ Oftentimes, the possible responses for a scalar field are enumerable. GraphQL
276
+ offers an ` Enum ` type in those cases, where the type specifies the set of valid
277
+ responses.
278
278
279
- GraphQL supports two abstract types: interfaces and unions.
279
+ :: A _ composite type_ is a type composed of other types via a set of named
280
+ fields. Each field may provide a _ leaf type_ or another composite type (or
281
+ wrapped types of either), allowing for the definition of arbitrary type
282
+ hierarchies.
280
283
281
- An ` Interface ` defines a list of fields; ` Object ` types and other Interface
282
- types which implement this Interface are guaranteed to implement those fields.
283
- Whenever a field claims it will return an Interface type, it will return a valid
284
- implementing Object type during execution.
284
+ An ` Object ` type is a _ composite type_ representing composite values selectable
285
+ within a GraphQL operation. They provide the intermediate levels of a schema,
286
+ allowing GraphQL to describe an interconnected graph of information.
285
287
286
- A ` Union ` defines a list of possible types; similar to interfaces, whenever the
287
- type system claims a union will be returned, one of the possible types will be
288
- returned.
288
+ :: An _ abstract type_ allows a GraphQL schema to introduce polymorphism; where a
289
+ field may provide one of many possible types at runtime. GraphQL provides two
290
+ kinds of abstract types: ` Interface ` and ` Union ` .
291
+
292
+ An ` Interface ` defines a list of fields; ` Object ` types and other ` Interface `
293
+ types which implement this ` Interface ` are guaranteed to implement those fields.
294
+ Whenever a field claims it will return an ` Interface ` type, it will return a
295
+ valid implementing ` Object ` type during execution.
296
+
297
+ A ` Union ` defines a list of possible types. Similar to ` Interfaces ` , whenever a
298
+ field claims it will return a ` Union ` type, it will return one of the possible
299
+ ` Object ` types during execution.
289
300
290
301
Finally, oftentimes it is useful to provide complex structs as inputs to GraphQL
291
- field arguments or variables; the ` Input Object ` type allows the schema to
292
- define exactly what data is expected.
302
+ field arguments or variables; the ` Input Object ` type is a _ composite type _
303
+ which allows the schema to define more complex expected input data .
293
304
294
305
### Wrapping Types
295
306
@@ -635,14 +646,14 @@ FieldDefinition : Description? Name ArgumentsDefinition? : Type
635
646
Directives [Const ]?
636
647
637
648
GraphQL operations are hierarchical and composed , describing a tree of
638
- information . While Scalar types describe the leaf values of these hierarchical
649
+ information . While _leaf types_ describe the leaf values of these hierarchical
639
650
operations , Objects describe the intermediate levels .
640
651
641
- GraphQL Objects represent a list of named fields , each of which yield a value of
642
- a specific type . Object values should be serialized as ordered maps , where the
643
- selected field names (or aliases) are the keys and the result of evaluating the
644
- field is the value , ordered by the order in which they appear in the selection
645
- set .
652
+ GraphQL Objects are a _composite type_ representing a list of named fields , each
653
+ of which yield a value of a specific type . Object values should be serialized as
654
+ ordered maps , where the selected field names (or aliases) are the keys and the
655
+ result of evaluating the field is the value , ordered by the order in which they
656
+ appear in the selection set .
646
657
647
658
All fields defined within an Object type must not have a name which begins with
648
659
{"\_\_" } (two underscores), as this is used exclusively by GraphQL 's
@@ -1052,9 +1063,14 @@ InterfaceTypeDefinition :
1052
1063
- Description ? interface Name ImplementsInterfaces ? Directives [Const ]?
1053
1064
[lookahead != `{`]
1054
1065
1055
- GraphQL interfaces represent a list of named fields and their arguments . GraphQL
1056
- objects and interfaces can then implement these interfaces which requires that
1057
- the implementing type will define all fields defined by those interfaces .
1066
+ GraphQL interfaces are an _abstract type_ which when used as the type of a field
1067
+ provides polymorphism where any implementation may be a possible type during
1068
+ execution .
1069
+
1070
+ Interfaces are also a _composite type_ as they represent a list of named fields
1071
+ and their arguments . An object or interface can declare that it implements an
1072
+ interface which requires that the implementing type will define all fields
1073
+ defined by that interface .
1058
1074
1059
1075
Fields on a GraphQL interface have the same rules as fields on a GraphQL object ;
1060
1076
their type can be Scalar , Object , Enum , Interface , or Union , or any wrapping
@@ -1304,17 +1320,18 @@ UnionMemberTypes :
1304
1320
- UnionMemberTypes | NamedType
1305
1321
- = `|`? NamedType
1306
1322
1307
- GraphQL Unions represent an object that could be one of a list of GraphQL Object
1308
- types , but provides for no guaranteed fields between those types . They also
1309
- differ from interfaces in that Object types declare what interfaces they
1310
- implement , but are not aware of what unions contain them .
1323
+ GraphQL Unions are an _abstract type_ representing one of a list of GraphQL
1324
+ Object possible types , but provides for no guaranteed fields between those
1325
+ types . They also differ from interfaces in that Object types declare what
1326
+ interfaces they implement , but are not aware of what unions contain them .
1311
1327
1312
1328
With interfaces and objects , only those fields defined on the type can be
1313
1329
queried directly ; to query other fields on an interface , typed fragments must be
1314
1330
used . This is the same as for unions , but unions do not define any fields , so
1315
1331
**no ** fields may be queried on this type without the use of type refining
1316
1332
fragments or inline fragments (with the exception of the meta-field
1317
- {\_\_typename}).
1333
+ {\_\_typename}). Despite this , a union is still considered a _composite type_ as
1334
+ it cannot represent a _leaf type_ .
1318
1335
1319
1336
For example , we might define the following types :
1320
1337
@@ -1429,8 +1446,9 @@ EnumValuesDefinition : { EnumValueDefinition+ }
1429
1446
1430
1447
EnumValueDefinition : Description ? EnumValue Directives [Const ]?
1431
1448
1432
- GraphQL Enum types , like Scalar types , also represent leaf values in a GraphQL
1433
- type system . However Enum types describe the set of possible values .
1449
+ GraphQL Enum types , like Scalar types , are a _leaf type_ which represents a
1450
+ _leaf field_ in a GraphQL type system . However Enum types describe the set of
1451
+ possible values .
1434
1452
1435
1453
Enums are not references for a numeric value , but are unique values in their own
1436
1454
right . They may serialize as a string : the name of the represented value .
0 commit comments