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.

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

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

Types

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

• Object types contain fields and describe our entities.
  Operations for example are nothing more than simple 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.

Besides those there are also enums, interfaces and unions.

Arguments

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

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.

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.

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

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.

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.

Schema evolution

As our data graph and number of developers/clients grows, we need to ensure everyone is on the same page.

Therefore, our schema should expose as much information to consumers of our API as possible. Besides Directives we can

• Add documentation to almost everything in our schema.

• Deprecate fields in anticipation of a breaking change.