Skip to main content

Fix ambiguity around when schema definition may be omitted

At a glance​

Timeline​

@rivantsov Pointed out in #978 that there's some ambiguity around when the schema keyword can be omitted from the SDL. Upon careful reading I've noticed that there is additional ambiguity around this topic.

While any type can be the root operation type for a GraphQL operation, the type system definition language can omit the schema definition when the {query}, {mutation}, and {subscription} root types are named {"Query"}, {"Mutation"}, and {"Subscription"} respectively.

This seems to imply that all the root types are required in order to omit the schema definition. I've modified the text to indicate that the names only need to match for the root types that are actually present.

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

Imagine we're doing biological research, tracking mutations in a virus. We might have a schema like:

type Query {
  viruses: [Virus!]
}
type Virus {
  name: String!
  knownMutations: [Mutation!]!
}
type Mutation {
  name: String!
  geneSequence: String!
}
schema {
  query: Query
}

In this case we must not omit the schema definition when representing the schema using the SDL, because doing so would make it seem that the Mutation type was the root type for the mutation operation, when in fact the schema does not support a mutation operation.

I've clarified the wording to deal with this possibility too.