In this section we will learn everything that is needed to build an expressive GraphQL schema.

Operations

First we will look at the three root types, often called Operations, that represent entry points to our schema:

• Queries allow us to query our graph and retrieve data in a readonly manner.
  Learn more about queries

• Mutations allow us to mutate our graph entities in the form of adding, removing or updating entities.
  Learn more about mutations

• Subscriptions allow us to subscribe to events in our system and be notified in real-time of their occurrence.
  Learn more about subscriptions

Types

Each GraphQL schema is made up of two basic building blocks:

• Object types contain fields and describe our entities.
  Learn more about object types

• Scalars are the primitives of our GraphQL schema: String, Int, etc.
  We can also define custom scalars to more precisely describe our business domain.
  Learn more about scalars

There are also more advanced types:

• Enums are a special kind of scalar, restricted to a particular set of allowed values.
  Learn more about enums
• Interfaces represent a shared contract that other types can implement.
  Learn more about interfaces
• Unions represent a set of object types, without the need for a shared contract.
  Learn more about unions.

Type Modifiers

Besides regular types, like scalars and object types, there are also type modifiers.

A non-null field for example indicates that a client can always expect a non-null value to be returned from the field.

Learn more about non-null

List fields indicate to a client that the field will return a list in the specified shape.

Learn more about lists

Arguments

We can pass arguments to individual fields on an object type and access their values inside the field's resolver.

Learn more about arguments

Nested object types can also be used as arguments by declaring so called input object types. These are most commonly used when passing a payload to a mutation.

Learn more about input object types

Extending Types

Hot Chocolate allows us to extend existing types, helping us keep our code organized.

Rather than adding more and more fields to the Query type in the same class for instance, we can extend the Query type with a new field from another location in our codebase where that field logically should live.

Learn more about extending types

Directives

Directives allow us to decorate parts of our GraphQL schema with additional configuration.

This configuration can be used as metadata for client tools or alternate our GraphQL server's runtime execution and type validation behavior.

Learn more about directives

Schema evolution

As our data graph and number of developers/clients grows, we need to ensure that the graph is understood by everyone. Therefore, our schema should expose as much information to consumers of our API as possible.

Learn more about schema documentation

Learn more about versioning

Relay

Relay proposes some schema design principles for GraphQL servers in order to more efficiently fetch, refetch and cache entities on the client. Since these principles make for a better schema, we encourage all users, not only those of Relay, to consider these principles.

Learn more about Relay-compatible schema design

Automatic type registration

Starting with Hot Chocolate 12.7 we introduced a new source generator that automatically registers types and DataLoader with your GraphQL configuration builder. Watch on YouTube how you can simplify your Hot Chocolate configuration code.