GraphQL schemas for a service are now most often specified using what’s known as the GraphQL SDL (schema definition language), also sometimes referred to as just GraphQL schema language. It’s a language with a very simple syntax that allows to define a schema very succinctly. Once you have a gasp at the different syntax elements of the SDL, you’ll be able to write schemas in no time flat.
The Basics
Here’s what a basic GraphQL schema deffinition for a simple todo app could look like:
# Enumeration type for a level of priority
enum Priority {
LOW
MEDIUM
HIGH
}
# Our main todo type
type Todo {
id: ID!
name: String!
description: String
priority: Priority!
}
type Query {
# Get one todo item
todo(id: ID!): Todo
# Get all todo items
allTodos: [Todo!]!
}
type Mutation {
addTodo(name: String!, priority: Priority = LOW): Todo!
removeTodo(id: ID!): Todo!
}
schema {
query: Query
mutation: Mutation
}
A lot is going on here, so let’s break down some of the most important things:
Object Types
Object types are specific to a GraphQL service, are defined with the type keyword and start with a capital letter by convention. They define the type name and the fields present under that type. Each field in an object type can be resolve to either other object types or scalar types. Scalar types point to actual data and represent the leaves of the graph.
In the above schema deffinition we have the Todo object type as well as the Query and Mutation root object types. Only the Query root type is required in all GraphQL schemas, but the mutation root type will most often also be present when the service allows for updating, adding or deleting data. Additionally, a Subscription root type is also available, to define operations that a client can subscribe to.
Built-In Scalar Types
There are 5 built-in scalar types with GraphQL: Int, Float, String, Boolean and ID. Scalar types, as opposed to object types, point to actual data. The ID type resolves to a string, but expects a unique value.
Enumeration Types
Enumeration types allow to define a specific subset of possible values for a type. In the previous example, the Priority enum type can take a value of LOW, MEDIUM or HIGH and anything else will result in a validation error. On the client strings are used to provide a value for an enum type.
Type Modifiers
As you can also see from the above example, modifiers can be used on the type that a field resolves to by using characters like ! and […]. Here’s a breakdown, using the String scalar type as an example:
- String: nullable string (the resolved value can be null)
- String!: Non-nullable string (if the resolved value is null, an error will be raised)
- [String]: Nullable list of nullable string values. The entire value can be null, or specific list elements can be null.
- [String!]: Nullable list of non-nullable string values. Then entire value can be null, but specific list elements cannot be null.
- [String!]!: Non-nullable list of non-nullable string values. Nothing can be null, neither the whole value nor the individual items. An empty list ([]) is still valid because the whole value is not null and there’s no individual null values.
Comments
Comments are added with the # symbol and only single-line comments are allowed.
Custom Scalar Types
It’s also possible to define custom scalar types with a syntax like this:
scalar DateTime
With this though, the GraphQL service will need to define how the custom scalar is to be serialized and validated.
Union Types
Union types define a type that can resolve to a number of possible object types:
# ...
union Vehicule = Car | Boat | Plane
type Query {
getVehicule(id: ID!): Vehicule!
}
With union types, on the client, inline fragments have to be used to select the desired fields depending on what subtype is being resolved:
query {
getVehicule {
...on Car {
year
}
...on Boat {
color
}
...on Plane {
seating
}
}
}
Interfaces
Interfaces are somewhat similar to union types, but they allow multiple object types to share some fields:
interface Vehicule {
color: String
make: String
speed: Int
}
type Car implements Vehicule {
color: String
make: String
speed: Int
model: String
}
# ...
Each type that implements an interface need to have fields corresponding to all the interface’s fields, but can also have aditional fields of their own. This way, on the client, inline fragments can be used to get fields that are unique to certain types:
graphql {
getVehicule {
color
make
...on Car {
model
}
}
}
Input Types
When a query or mutation expects multiple arguments, it can be easier to define input types where each field represents an argument:
# ...
input NewTodoInput {
name: String!
priority: Priority = LOW
}
type Mutation {
addTodo(newTodoInput: NewTodoInput!): Todo!
removeTodo(id: ID!): Todo!
}
Schema Documentation
There’s also a syntax to add human-readable documentation for types and fields, which can become really helpful when using a tool like GraphiQL or GraphQL Playground to browse the documentation for a schema.
Let’s take our initial todo schema example and add some documentation for the types and some of the fields:
"""
Priority level
"""
enum Priority {
LOW
MEDIUM
HIGH
}
type Todo {
id: ID!
name: String!
"""
Useful description for todo item
"""
description: String
priority: Priority!
}
"""
Queries available on the todo app service
"""
type Query {
"""
Get one todo item
"""
todo(id: ID!): Todo
"""
List of all todo items
"""
allTodos: [Todo!]!
}
type Mutation {
addTodo(
"Name for the todo item"
name: String!
"Priority levl of todo item"
priority: Priority = LOW): Todo!
removeTodo(id: ID!): Todo!
}
schema {
query: Query
mutation: Mutation
}
As you can see, documentation for types or fields is added by wrapping with the ””” … “”” syntax. The ” … “ is used for documentaion on arguments.
🚀 With this you should be off to the races with defining GraphQL schemas. You can also always refer to the official spec when you're unsure about some of the syntax.