GraphQL types: What is the correct bucketing?

Question

Neither the official graphql guide, nor the howtographql tutorial, specifies a consistent bucketing / hierarchy of types.

From the Official "Learn" GraphQL:

The most basic components of a GraphQL schema are object types

...

Most types in your schema will just be normal object types, but there are two types that are special within a schema: Query, Mutation. [my note: Here they forgot subscription]

...

Except for being "entry point" into schema, Query and Mutation types are the same as any other GraphQL object type, and their fields work exactly the same way

...

That's where the scalar types come in: they represent the leaves of the query

...

Enumeration types are a special kind of scalar

...

Object types, scalars, and enums are the only kinds of types you can define in GraphQL. [my note: That is not entirely correct, as enums are special scalar types]

...

An Interface is an abstract type

...

Union types are very similar to interfaces

...

Input types look exactly the same as regular object types, but with the keyword input instead of type

From HowToGraphQL:

In GraphQL, there are two different kinds of types.

• Scalar types

• Object types

...

enums are special kinds of scalar types.

...

An interface can be used to describe a type in an abstract way.

...

Union types can be used to express that a type should be either of a collection of other types.

My Best Guess

• There only exists two types in GraphQL:
  • Object type
  • Scalar type
• Object type includes
  • Custom object types
  • 3 special object types: Query, Mutation, Subscription
• Scalar type includes
  • 5 built-in scalar types
  • Custom scalar types
  • Enumeration type
• Interface and Union
  • These are not actually types
  • They are mechanisms used to describe object types
• Input type
  • Again, not actually a type
  • It is a mechanism through which object and scalar types can be used as inputs in queries

Question

Is there a correct (official) bucketing? Is my "best guess" above correct?

Answer 1

GraphQL has a specification that describes the type system in detail. I would read the specification carefully, as it may answer other questions you have about GraphQL as well. You should take what other websites state with a grain of salt as it may be either outright wrong, use the incorrect terminology or oversimplify things (to not overwhelm readers that are new to GraphQL).

The fundamental unit of any GraphQL Schema is the type. There are six kinds of named type definitions in GraphQL, and two wrapping types.

The most basic type is a Scalar. A scalar represents a primitive value, like a string or an integer. Oftentimes, the possible responses for a scalar field are enumerable. GraphQL offers an Enum type in those cases, where the type specifies the space of valid responses.

Scalars and Enums form the leaves in response trees; the intermediate levels are Object types, which define a set of fields, where each field is another type in the system, allowing the definition of arbitrary type hierarchies.

GraphQL supports two abstract types: interfaces and unions.

An Interface defines a list of fields; Object types that implement that interface are guaranteed to implement those fields. Whenever the type system claims it will return an interface, it will return a valid implementing type.

A Union defines a list of possible types; similar to interfaces, whenever the type system claims a union will be returned, one of the possible types will be returned.

Finally, oftentimes it is useful to provide complex structs as inputs to GraphQL field arguments or variables; the Input Object type allows the schema to define exactly what data is expected.

The two wrapper types the spec mentions -- List and Non-Null are described later. A List is "a special collection type which declares the type of each item in the List", while a Non-Null wraps an existing type and makes null an invalid response (all types are nullable by default).

The spec also describes root operation types. There are three root operation types -- query, mutation and subscription. Only query is required. These are not separate types in themselves, both rather parts of the schema definition that effectively point to some other type. All three must be Object types.

schema {
  query: Foo
}

type Foo {
  someField: String
}