The schema in GraphQL represents the type system and exposes your business model in a strong and rich way. The schema fully describes the shape of your data and how you can interact with it.
Object Type
The most important type in a GraphQL schema is the object type which lets you consume data. Every object type has to have at least one field which holds the data of an object. Fields can return simple scalars like String, Int, or again object types.
type Book {
title: String
author: String
}Operations
In GraphQL, we have three root types from which only the Query type has to be defined. Root types provide the entry points that let you fetch data, mutate data, or subscribe to events. Root types themself are object types.
schema {
query: Query
}
type Query {
book: Book
}
type Book {
title: String
author: String
}In Hot Chocolate, there are three ways to define an object type.
Note: Every single code example will be shown in three different approaches, annotation-based (previously known as pure code-first), code-first, and schema-first. However, they will always result in the same outcome on a GraphQL schema perspective and internally in Hot Chocolate. All three approaches have their pros and cons and can be combined when needed with each other. If you would like to learn more about the three approaches in Hot Chocolate, click on Coding Approaches.
Annotation-based approach
// Query.cs
public class Query
{
public Book GetBook() => new Book { Title = "C# in depth", Author = "Jon Skeet" };
}
// Book.cs
public class Book
{
public string Title { get; set; }
public string Author { get; set; }
}
// Startup.cs
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services
.AddRouting()
.AddGraphQLServer()
.AddQueryType<Query>();
}
// Omitted code for brevity
}Code-first approach
// Query.cs
public class Query
{
public Book GetBook() => new Book { Title = "C# in depth", Author = "Jon Skeet" };
}
// QueryType.cs
public class QueryType : ObjectType<Query>
{
protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
{
descriptor
.Field(f => f.GetBook())
.Type<BookType>();
}
}
// Book.cs
public class Book
{
public string Title { get; set; }
public string Author { get; set; }
}
// BookType.cs
public class BookType : ObjectType<Book>
{
protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
{
descriptor
.Field(f => f.Title)
.Type<StringType>();
descriptor
.Field(f => f.Author)
.Type<StringType>();
}
}
// Startup.cs
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services
.AddRouting()
.AddGraphQLServer()
.AddQueryType<QueryType>();
}
// Omitted code for brevity
}Schema-first approach
// Query.cs
public class Query
{
public Book GetBook() => new Book { Title = "C# in depth", Author = "Jon Skeet" };
}
// Startup.cs
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services
.AddRouting()
.AddGraphQLServer()
.AddDocumentFromString(@"
type Query {
book: Book
}
type Book {
title: String
author: String
}
")
.BindComplexType<Query>();
}
// Omitted code for brevity
}Fields
Fields of object types can be compared to methods in C# and allow us to pass in arguments.
type Query {
book(id: String): Book
}
type Book {
title: String
author: String
}{
book(id: "abc") {
title
}
}Annotation-based approach
// Query.cs
public class Query
{
public Task<Book> GetBookAsync(string id)
{
// Omitted code for brevity
}
}
// Book.cs
public class Book
{
public string Title { get; set; }
public string Author { get; set; }
}
// Startup.cs
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services
.AddRouting()
.AddGraphQLServer()
.AddQueryType<Query>();
}
// Omitted code for brevity
}Code-first approach
// Query.cs
public class Query
{
public Task<Book> GetBookAsync(string id)
{
// Omitted code for brevity
}
}
// QueryType.cs
public class QueryType : ObjectType<Query>
{
protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
{
descriptor
.Field(f => f.GetBook(default))
.Type<BookType>();
}
}
// Book.cs
public class Book
{
public string Title { get; set; }
public string Author { get; set; }
}
// BookType.cs
public class BookType : ObjectType<Book>
{
protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
{
descriptor
.Field(f => f.Title)
.Type<StringType>();
descriptor
.Field(f => f.Author)
.Type<StringType>();
}
}
// Startup.cs
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services
.AddRouting()
.AddGraphQLServer()
.AddQueryType<QueryType>();
}
// Omitted code for brevity
}Schema-first approach
// Query.cs
public class Query
{
public Task<Book> GetBookAsync(string id)
{
// Omitted code for brevity
}
}
// Startup.cs
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services
.AddRouting()
.AddGraphQLServer()
.AddDocumentFromString(@"
type Query {
book(id: String): Book
}
type Book {
title: String
author: String
}
")
.BindComplexType<Query>();
}
// Omitted code for brevity
}Further reading:
Input Objects
In GraphQL we distinguish between input- and output-types. We already learned about object types which is the most prominent output-type and lets us consume data. Further, we used simple scalars like String to pass data into a field as an argument. In order to define complex structures of raw data that can be used as input data GraphQL defines input objects.
input BookInput {
title: String
author: String
}If we wanted for instance to create a new book with a mutation we could do that like the following.
Annotation-based approach
// Query.cs
public class Query
{
// Omitted code for brevity
}
// Query.cs
public class Mutation
{
public async Task<Book> CreateBook(Book book)
{
}
}
// Book.cs
public class Book
{
public string Title { get; set; }
public string Author { get; set; }
}
// Startup.cs
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services
.AddRouting()
.AddGraphQLServer()
.AddQueryType<Query>();
}
// Omitted code for brevity
}Code-first approach
// Query.cs
public class Query
{
public Task<Book> GetBookAsync(string id)
{
// Omitted code for brevity
}
}
// QueryType.cs
public class QueryType : ObjectType<Query>
{
protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
{
descriptor
.Field(f => f.GetBook(default))
.Type<BookType>();
}
}
// Book.cs
public class Book
{
public string Title { get; set; }
public string Author { get; set; }
}
// BookType.cs
public class BookType : ObjectType<Book>
{
protected override void Configure(IObjectTypeDescriptor<Query> descriptor)
{
descriptor
.Field(f => f.Title)
.Type<StringType>();
descriptor
.Field(f => f.Author)
.Type<StringType>();
}
}
// Startup.cs
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services
.AddRouting()
.AddGraphQLServer()
.AddQueryType<QueryType>();
}
// Omitted code for brevity
}Schema-first approach
// Query.cs
public class Query
{
public Task<Book> GetBookAsync(string id)
{
// Omitted code for brevity
}
}
// Startup.cs
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services
.AddRouting()
.AddGraphQLServer()
.AddDocumentFromString(@"
type Query {
book(id: String): Book
}
type Book {
title: String
author: String
}
")
.BindComplexType<Query>();
}
// Omitted code for brevity
}Lists
Nullability
GraphQL has a concept of nun-null types. Basically any type can be a non-nullable type, in the SDL we decorate non-nullable types with the Bang token !. In order to describe this in C# we can use attributes, use C# nullable reference types or use the underlying schema types to describe our GraphQL type explicitly.