Skip to content

Commit 4e93488

Browse files
benjieleebyron
andauthored
Fix ambiguity around when schema definition may be omitted (#987)
Clarify that a schema definition must be present (and not omitted) if a default root type name happens to be used by a type which is not a root type. Also adds an editorial change to introduce term definitions for the immediate concepts involved. Co-authored-by: Lee Byron <lee@leebyron.com>
1 parent 12b7ad7 commit 4e93488

File tree

1 file changed

+48
-19
lines changed

1 file changed

+48
-19
lines changed

spec/Section 3 -- Type System.md

Lines changed: 48 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ RootOperationTypeDefinition : OperationType : NamedType
122122

123123
A GraphQL service's collective type system capabilities are referred to as that
124124
service's "schema". A schema is defined in terms of the types and directives it
125-
supports as well as the root operation types for each kind of operation: query,
125+
supports as well as the _root operation type_ for each kind of operation: query,
126126
mutation, and subscription; this determines the place in the type system where
127127
those operations begin.
128128

@@ -141,24 +141,24 @@ introspection system.
141141

142142
### Root Operation Types
143143

144-
A schema defines the initial root operation type for each kind of operation it
145-
supports: query, mutation, and subscription; this determines the place in the
144+
:: A schema defines the initial _root operation type_ for each kind of operation
145+
it supports: query, mutation, and subscription; this determines the place in the
146146
type system where those operations begin.
147147

148-
The {`query`} root operation type must be provided and must be an Object type.
148+
The {`query`} _root operation type_ must be provided and must be an Object type.
149149

150-
The {`mutation`} root operation type is optional; if it is not provided, the
150+
The {`mutation`} _root operation type_ is optional; if it is not provided, the
151151
service does not support mutations. If it is provided, it must be an Object
152152
type.
153153

154-
Similarly, the {`subscription`} root operation type is also optional; if it is
154+
Similarly, the {`subscription`} _root operation type_ is also optional; if it is
155155
not provided, the service does not support subscriptions. If it is provided, it
156156
must be an Object type.
157157

158158
The {`query`}, {`mutation`}, and {`subscription`} root types must all be
159159
different types if provided.
160160

161-
The fields on the {`query`} root operation type indicate what fields are
161+
The fields on the {`query`} _root operation type_ indicate what fields are
162162
available at the top level of a GraphQL query operation.
163163

164164
For example, this example operation:
@@ -169,16 +169,17 @@ query {
169169
}
170170
```
171171

172-
is only valid when the {`query`} root operation type has a field named "myName":
172+
is only valid when the {`query`} _root operation type_ has a field named
173+
"myName":
173174

174175
```graphql example
175176
type Query {
176177
myName: String
177178
}
178179
```
179180

180-
Similarly, the following mutation is only valid if the {`mutation`} root
181-
operation type has a field named "setName".
181+
Similarly, the following mutation is only valid if the {`mutation`} _root
182+
operation type_ has a field named "setName".
182183

183184
```graphql example
184185
mutation {
@@ -191,8 +192,8 @@ mutation {
191192
When using the type system definition language, a document must include at most
192193
one {`schema`} definition.
193194

194-
In this example, a GraphQL schema is defined with both query and mutation root
195-
operation types:
195+
In this example, a GraphQL schema is defined with both a query and mutation
196+
_root operation type_:
196197

197198
```graphql example
198199
schema {
@@ -211,25 +212,53 @@ type MyMutationRootType {
211212

212213
**Default Root Operation Type Names**
213214

214-
While any type can be the root operation type for a GraphQL operation, the type
215-
system definition language can omit the schema definition when the {`query`},
216-
{`mutation`}, and {`subscription`} root types are named {"Query"}, {"Mutation"},
217-
and {"Subscription"} respectively.
215+
:: The _default root type name_ for each {`query`}, {`mutation`}, and
216+
{`subscription`} _root operation type_ are {"Query"}, {"Mutation"}, and
217+
{"Subscription"} respectively.
218+
219+
The type system definition language can omit the schema definition when each
220+
_root operation type_ uses its respective _default root type name_ and no other
221+
type uses any _default root type name_.
218222

219223
Likewise, when representing a GraphQL schema using the type system definition
220-
language, a schema definition should be omitted if it only uses the default root
221-
operation type names.
224+
language, a schema definition should be omitted if each _root operation type_
225+
uses its respective _default root type name_ and no other type uses any _default
226+
root type name_.
222227

223228
This example describes a valid complete GraphQL schema, despite not explicitly
224229
including a {`schema`} definition. The {"Query"} type is presumed to be the
225-
{`query`} root operation type of the schema.
230+
{`query`} _root operation type_ of the schema.
226231

227232
```graphql example
228233
type Query {
229234
someField: String
230235
}
231236
```
232237

238+
This example describes a valid GraphQL schema without a {`mutation`} _root
239+
operation type_, even though it contains a type named {"Mutation"}. The schema
240+
definition must be included, otherwise the {"Mutation"} type would be
241+
incorrectly presumed to be the {`mutation`} _root operation type_ of the schema.
242+
243+
```graphql example
244+
schema {
245+
query: Query
246+
}
247+
248+
type Query {
249+
latestVirus: Virus
250+
}
251+
252+
type Virus {
253+
name: String
254+
mutations: [Mutation]
255+
}
256+
257+
type Mutation {
258+
name: String
259+
}
260+
```
261+
233262
### Schema Extension
234263

235264
SchemaExtension :

0 commit comments

Comments
 (0)