Skip to content

Commit 2c2cea7

Browse files
authored
Editorial: root types (#842)
Clarify use of root types and improve formatting. Factored out of #777
1 parent 080c8b6 commit 2c2cea7

File tree

1 file changed

+21
-17
lines changed

1 file changed

+21
-17
lines changed

spec/Section 3 -- Type System.md

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -133,36 +133,40 @@ A schema defines the initial root operation type for each kind of operation it
133133
supports: query, mutation, and subscription; this determines the place in the
134134
type system where those operations begin.
135135

136-
The `query` root operation type must be provided and must be an Object type.
136+
The {`query`} root operation type must be provided and must be an Object type.
137137

138-
The `mutation` root operation type is optional; if it is not provided, the
138+
The {`mutation`} root operation type is optional; if it is not provided, the
139139
service does not support mutations. If it is provided, it must be an
140140
Object type.
141141

142-
Similarly, the `subscription` root operation type is also optional; if it is not
143-
provided, the service does not support subscriptions. If it is provided, it must
144-
be an Object type.
142+
Similarly, the {`subscription`} root operation type is also optional; if it is
143+
not provided, the service does not support subscriptions. If it is provided, it
144+
must be an Object type.
145145

146-
The fields on the `query` root operation type indicate what fields are available
147-
at the top level of a GraphQL query. For example, a basic GraphQL query like:
146+
The {`query`}, {`mutation`}, and {`subscription`} root types must all be
147+
different types if provided.
148+
149+
The fields on the {`query`} root operation type indicate what fields are
150+
available at the top level of a GraphQL query operation.
151+
152+
For example, this example operation:
148153

149154
```graphql example
150155
query {
151156
myName
152157
}
153158
```
154159

155-
Is valid when the `query` root operation type has a field named "myName".
160+
is only valid when the {`query`} root operation type has a field named "myName":
156161

157162
```graphql example
158163
type Query {
159164
myName: String
160165
}
161166
```
162167

163-
Similarly, the following mutation is valid if a `mutation` root operation type
164-
has a field named "setName". Note that the `query` and `mutation` root types
165-
must be different types.
168+
Similarly, the following mutation is only valid if the {`mutation`} root
169+
operation type has a field named "setName".
166170

167171
```graphql example
168172
mutation {
@@ -173,7 +177,7 @@ mutation {
173177
```
174178

175179
When using the type system definition language, a document must include at most
176-
one `schema` definition.
180+
one {`schema`} definition.
177181

178182
In this example, a GraphQL schema is defined with both query and mutation
179183
root types:
@@ -196,17 +200,17 @@ type MyMutationRootType {
196200
**Default Root Operation Type Names**
197201

198202
While any type can be the root operation type for a GraphQL operation, the type
199-
system definition language can omit the schema definition when the `query`,
200-
`mutation`, and `subscription` root types are named `Query`, `Mutation`, and
201-
`Subscription` respectively.
203+
system definition language can omit the schema definition when the {`query`},
204+
{`mutation`}, and {`subscription`} root types are named {"Query"}, {"Mutation"},
205+
and {"Subscription"} respectively.
202206

203207
Likewise, when representing a GraphQL schema using the type system definition
204208
language, a schema definition should be omitted if it only uses the default root
205209
operation type names.
206210

207211
This example describes a valid complete GraphQL schema, despite not explicitly
208-
including a `schema` definition. The `Query` type is presumed to be the `query`
209-
root operation type of the schema.
212+
including a {`schema`} definition. The {"Query"} type is presumed to be the
213+
{`query`} root operation type of the schema.
210214

211215
```graphql example
212216
type Query {

0 commit comments

Comments
 (0)