Skip to main content

"Root" Types clarity → "Operation Type"

At a glance​

Timeline​

This attempts to clarify some naming conventions in the spec and makes one meaningful syntax change.

This changes SchemaDefinition to have a zero-or-more list of OperationTypeDefinition rather than one-or-more. It removes some language that refers to this "at least one" requirement as well.

Why? Because schema can be extended with SchemaExtension. This brings this into consistency with other elements of the type definition language where definitions allow providing zero items for aspects that require​ one at the point of schema validation. This was overlooked before since most people use the default names, but it is not required to do so, and sometimes you need to supply the schema definition for explicitness, but are within the context of a single file that is a subset of a full schema where other operation types are defined elsewhere.

Specifically, this example used to not parse, and now should:

schema {}

What has not changed is that schema are required to provide a query root type. A schema without this operation type will not pass validation, and would later need something like this to become valid:

extend schema { query: MyQueryType }

The bulk of this change edits naming of some concepts in an attempt to improve clarity:

  • Renames OperationType to OperationKind. This was already inconsistently used throughout the spec doc, but now is consistently using "kind". This avoids overloading the term "type".

  • Renames RootOperationTypeDefinition to OperationTypeDefinition. We use "root" in an overloaded way and this was redundant. This improves the text to be a well defined provider of the type for a root selection set of an operation, so this shorter name is less redundant and easier to read. This also renames "default root type name" to "default operation type name" for consistency.

  • Replaces "root field" with "root selection set". A root field is a holdover concept from a 10yr old version of GraphQL. More accurately today these are "fields on the root selection set". This makes the latter well defined. I searched for "root" to make sure it refers only to a well defined "root selection set". This our last and only remaining use of the term "root".

  • Minor editorial change where we only use a the form {`query`} when referring to the actual keyword rather than the concept