Skip to content

Commit e228161

Browse files
committed
add related definition and specific example
1 parent 2130bfa commit e228161

File tree

1 file changed

+46
-20
lines changed

1 file changed

+46
-20
lines changed

spec/Section 3 -- Type System.md

+46-20
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,18 +212,18 @@ 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
215-
_default root type name_ for the {`query`}, {`mutation`}, and {`subscription`}
216-
root types are {"Query"}, {"Mutation"}, 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.
217218

218219
The type system definition language can omit the schema definition when each
219-
root type present uses its respective _default root type name_ and no other type
220-
uses a default root type name.
220+
_root operation type_ uses its respective _default root type name_ and no other
221+
type uses any _default root type name_.
221222

222223
Likewise, when representing a GraphQL schema using the type system definition
223-
language, a schema definition should be omitted if each root type present uses
224-
its respective _default root type name_ and no other type uses a default root
225-
type name.
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_.
226227

227228
This example describes a valid complete GraphQL schema, despite not explicitly
228229
including a {`schema`} definition. The {"Query"} type is presumed to be the
@@ -234,6 +235,31 @@ type Query {
234235
}
235236
```
236237

238+
While this example describes a valid GraphQL schema which happens to contain a
239+
type called {"Mutation"} which is not the {`mutation`} _root operation type_.
240+
Even though {"Query"} is a _default root type name_, the schema definition must
241+
still be printed to indicate that it does not provide a {`mutation`} _root
242+
operation type_.
243+
244+
```graphql example
245+
schema {
246+
query: Query
247+
}
248+
249+
type Query {
250+
latestVirus: Virus
251+
}
252+
253+
type Virus {
254+
name: String
255+
mutations: Mutation[]
256+
}
257+
258+
type Mutation {
259+
name: String
260+
}
261+
```
262+
237263
### Schema Extension
238264

239265
SchemaExtension :

0 commit comments

Comments
 (0)