Skip to content

Commit d7d9e37

Browse files
committed
Be explicit about the ordering of data types
1 parent 368a48b commit d7d9e37

File tree

1 file changed

+30
-23
lines changed

1 file changed

+30
-23
lines changed

spec/Section 3 -- Type System.md

+30-23
Original file line numberDiff line numberDiff line change
@@ -302,17 +302,18 @@ enumerable. GraphQL offers an `Enum` type in those cases, where the type
302302
specifies the space of valid responses.
303303

304304
Scalars and Enums form the leaves in response trees; the intermediate levels are
305-
`Object` types, which define a set of fields, where each field is another type
306-
in the system, allowing the definition of arbitrary type hierarchies.
305+
`Object` types, which define an ordered set of fields, where each field is
306+
another type in the system, allowing the definition of arbitrary type
307+
hierarchies.
307308

308309
GraphQL supports two abstract types: interfaces and unions.
309310

310-
An `Interface` defines a list of fields; `Object` types and other Interface
311-
types which implement this Interface are guaranteed to implement those fields.
312-
Whenever a field claims it will return an Interface type, it will return a valid
313-
implementing Object type during execution.
311+
An `Interface` defines an ordered set of fields; `Object` types and other
312+
Interface types which implement this Interface are guaranteed to implement those
313+
fields. Whenever a field claims it will return an Interface type, it will return
314+
a valid implementing Object type during execution.
314315

315-
A `Union` defines a list of possible types; similar to interfaces, whenever the
316+
A `Union` defines a set of possible types; similar to interfaces, whenever the
316317
type system claims a union will be returned, one of the possible types will be
317318
returned.
318319

@@ -674,11 +675,11 @@ GraphQL operations are hierarchical and composed, describing a tree of
674675
information. While Scalar types describe the leaf values of these hierarchical
675676
operations, Objects describe the intermediate levels.
676677

677-
GraphQL Objects represent a list of named fields, each of which yield a value of
678-
a specific type. Object values should be serialized as ordered maps, where the
679-
selected field names (or aliases) are the keys and the result of evaluating the
680-
field is the value, ordered by the order in which they appear in the _selection
681-
set_.
678+
GraphQL Objects represent an ordered set of named fields, each of which yield a
679+
value of a specific type. Object values should be serialized as ordered maps,
680+
where the selected field names (or aliases) are the keys and the result of
681+
evaluating the field is the value, ordered by the order in which they appear in
682+
the _selection set_.
682683

683684
All fields defined within an Object type must not have a name which begins with
684685
{"\_\_"} (two underscores), as this is used exclusively by GraphQL's
@@ -920,7 +921,8 @@ of rules must be adhered to by every Object type in a GraphQL schema.
920921
returns {true}.
921922
4. If argument type is Non-Null and a default value is not defined:
922923
1. The `@deprecated` directive must not be applied to this argument.
923-
3. An object type may declare that it implements one or more unique interfaces.
924+
3. An object type may declare that it implements a set of one or more unique
925+
interfaces.
924926
4. An object type must be a super-set of all interfaces it implements:
925927
1. Let this object type be {objectType}.
926928
2. For each interface declared implemented as {interfaceType},
@@ -982,7 +984,7 @@ InputValueDefinition : Description? Name : Type DefaultValue? Directives[Const]?
982984

983985
Object fields are conceptually functions which yield values. Occasionally object
984986
fields can accept arguments to further specify the return value. Object field
985-
arguments are defined as a list of all possible argument names and their
987+
arguments are defined as an ordered set of all possible argument names and their
986988
expected input types.
987989

988990
All arguments defined within a field must not have a name which begins with
@@ -1093,9 +1095,10 @@ InterfaceTypeDefinition :
10931095
- Description? interface Name ImplementsInterfaces? Directives[Const]?
10941096
[lookahead != `{`]
10951097

1096-
GraphQL interfaces represent a list of named fields and their arguments. GraphQL
1097-
objects and interfaces can then implement these interfaces which requires that
1098-
the implementing type will define all fields defined by those interfaces.
1098+
GraphQL interfaces represent an ordered set of named fields and their arguments.
1099+
GraphQL objects and interfaces can then implement these interfaces which
1100+
requires that the implementing type will define all fields defined by those
1101+
interfaces.
10991102

11001103
Fields on a GraphQL interface have the same rules as fields on a GraphQL object;
11011104
their type can be Scalar, Object, Enum, Interface, or Union, or any wrapping
@@ -1347,7 +1350,7 @@ UnionMemberTypes :
13471350
- UnionMemberTypes | NamedType
13481351
- = `|`? NamedType
13491352

1350-
GraphQL Unions represent an object that could be one of a list of GraphQL Object
1353+
GraphQL Unions represent an object that could be one of a set of GraphQL Object
13511354
types, but provides for no guaranteed fields between those types. They also
13521355
differ from interfaces in that Object types declare what interfaces they
13531356
implement, but are not aware of what unions contain them.
@@ -1408,7 +1411,7 @@ A valid operation includes typed fragments (in this example, inline fragments):
14081411
```
14091412

14101413
Union members may be defined with an optional leading `|` character to aid
1411-
formatting when representing a longer list of possible types:
1414+
formatting when representing a longer set of possible types:
14121415

14131416
```raw graphql example
14141417
union SearchResult =
@@ -1547,9 +1550,9 @@ InputFieldsDefinition : { InputValueDefinition+ }
15471550
Fields may accept arguments to configure their behavior. These inputs are often
15481551
scalars or enums, but they sometimes need to represent more complex values.
15491552

1550-
A GraphQL Input Object defines a set of input fields; the input fields are
1551-
either scalars, enums, or other input objects. This allows arguments to accept
1552-
arbitrarily complex structs.
1553+
A GraphQL Input Object defines an ordered set of named input fields; the input
1554+
fields are either scalars, enums, or other input objects. This allows arguments
1555+
to accept arbitrarily complex structs.
15531556

15541557
In this example, an Input Object called `Point2D` describes `x` and `y` inputs:
15551558

@@ -1936,6 +1939,10 @@ A GraphQL schema describes directives which are used to annotate various parts
19361939
of a GraphQL document as an indicator that they should be evaluated differently
19371940
by a validator, executor, or client tool such as a code generator.
19381941

1942+
Directives can accept arguments to further specify their behavior. Directive
1943+
arguments are defined as an ordered set of all possible argument names and their
1944+
expected input types.
1945+
19391946
**Built-in Directives**
19401947

19411948
:: A _built-in directive_ is any directive defined within this specification.
@@ -1983,7 +1990,7 @@ fragment SomeFragment on SomeType {
19831990
```
19841991

19851992
Directive locations may be defined with an optional leading `|` character to aid
1986-
formatting when representing a longer list of possible locations:
1993+
formatting when representing a longer set of possible locations:
19871994

19881995
```raw graphql example
19891996
directive @example on

0 commit comments

Comments
 (0)