Skip to content

Commit 493121c

Browse files
committed
Clarify more types
1 parent 5cbfeb4 commit 493121c

File tree

2 files changed

+25
-23
lines changed

2 files changed

+25
-23
lines changed

spec/Section 3 -- Type System.md

+23-21
Original file line numberDiff line numberDiff line change
@@ -302,15 +302,16 @@ 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

315316
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
@@ -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,7 @@ 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 a list of one or more unique
924+
3. An object type may declare that it implements a set of one or more unique
924925
interfaces.
925926
4. An object type must be a super-set of all interfaces it implements:
926927
1. Let this object type be {objectType}.
@@ -983,7 +984,7 @@ InputValueDefinition : Description? Name : Type DefaultValue? Directives[Const]?
983984

984985
Object fields are conceptually functions which yield values. Occasionally object
985986
fields can accept arguments to further specify the return value. Object field
986-
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
987988
expected input types.
988989

989990
All arguments defined within a field must not have a name which begins with
@@ -1094,9 +1095,10 @@ InterfaceTypeDefinition :
10941095
- Description? interface Name ImplementsInterfaces? Directives[Const]?
10951096
[lookahead != `{`]
10961097

1097-
GraphQL interfaces represent a list of named fields and their arguments. GraphQL
1098-
objects and interfaces can then implement these interfaces which requires that
1099-
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.
11001102

11011103
Fields on a GraphQL interface have the same rules as fields on a GraphQL object;
11021104
their type can be Scalar, Object, Enum, Interface, or Union, or any wrapping
@@ -1348,7 +1350,7 @@ UnionMemberTypes :
13481350
- UnionMemberTypes | NamedType
13491351
- = `|`? NamedType
13501352

1351-
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
13521354
types, but provides for no guaranteed fields between those types. They also
13531355
differ from interfaces in that Object types declare what interfaces they
13541356
implement, but are not aware of what unions contain them.
@@ -1548,9 +1550,9 @@ InputFieldsDefinition : { InputValueDefinition+ }
15481550
Fields may accept arguments to configure their behavior. These inputs are often
15491551
scalars or enums, but they sometimes need to represent more complex values.
15501552

1551-
A GraphQL Input Object defines a list of named input fields; the input fields
1552-
are either scalars, enums, or other input objects. This allows arguments to
1553-
accept 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.
15541556

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

@@ -1938,7 +1940,7 @@ of a GraphQL document as an indicator that they should be evaluated differently
19381940
by a validator, executor, or client tool such as a code generator.
19391941

19401942
Directives can accept arguments to further specify their behavior. Directive
1941-
arguments are defined as a list of all possible argument names and their
1943+
arguments are defined as an ordered set of all possible argument names and their
19421944
expected input types.
19431945

19441946
**Built-in Directives**

spec/Section 4 -- Introspection.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -122,8 +122,8 @@ warnings.
122122
When possible implementations should preserve observable order for unordered
123123
data collections. For example, if a schema was produced from a source
124124
{TypeSystemDocument} then introspection of fields, input fields, arguments, enum
125-
values, directives and so on should produce the same order as found in the
126-
source.
125+
values, directives, union members, implemented interfaces and so on should
126+
produce the same order as found in the source.
127127

128128
Note: This recommendation is to improve legibility and stability of schema
129129
representations.

0 commit comments

Comments
 (0)