2. The enum type
5m

Overview

In the Odyssey Lift-off series, we learned how to write a schema with fields that returned scalar or object types.

With a scalar type like Int or String, a field could have a huge number of possible values. But sometimes, you want to limit a field's return value to just a few options. It's like using a dropdown selector and selecting from a list of pre-validated values instead of using an empty text input and typing in whatever comes to mind!

This is where the enum type comes in handy!

In this lesson, we will:

  • Learn what an enum is, and how to define one in a GraphQL schema
  • See an example of how enums are used in the Airlock codebase

What is an enum?

An enum is a GraphQL schema type that represents a predefined list of possible values.

For example, in Airlock, listings can be a certain type of location: a spaceship, house, campsite, apartment, or room. We represent this in our schema through a locationType field.

Using what we know so far, we could define the locationType field as a String. But then we might run into consistency problems with our data. For example, what happens if a user accidentally types "space ship" instead of "spaceship"? Or what if they enter a value that isn't a valid location type, like "narwhal" or "pickle chips"? We might end up with unnecessary complications when filtering or organizing our listings.

To keep our data clean and consistent, it would be helpful to restrict the locationType field to a smaller set of possible values. We define this constraint in the schema through an enum.

Defining an enum

To define an enum, we start with the enum keyword, followed by the name of the enum in PascalCase, then curly braces ({}). Inside the curly braces, we add the list of possible values. By convention, these values are listed in all caps.

Here's an example of how we define an enum for the possible location types in Airlock:

server/schema.graphql
enum LocationType {
SPACESHIP
HOUSE
CAMPSITE
APARTMENT
ROOM
}

Using the enum

Once an enum has been defined, we can use it as a field's return type, the same way we would with any other scalar or object type.

Here's how the LocationType enum gets used for the Listing type's locationType field:

server/schema.graphql
type Listing {
# ...
"The location type of the listing"
locationType: LocationType!
# ...
}

This means that when we query for a particular listing's locationType, it will return one of the options listed under the LocationType enum.

query GetListingType {
listing(id: "listing-1") {
locationType # returns CAMPSITE
}
}

See it in the Airlock codebase

There are multiple enums defined in the Airlock schema. Check them out in the server/schema.graphql file.

  • What do you notice about the existing enums in the schema?
  • What other fields might be good candidates to return an enum? What possible values might that enum have?

Practice

Code Challenge!

In the schema definition below, define a new enum called OrderStatus with the following possible values: SUBMITTED, CONFIRMED, SHIPPED, DELIVERED, or CANCELLED. Then add a new field called orderStatus to the Order type, and make it resolve to a (non-null) value from the new enum.

Key takeaways

  • An enum type defines a preset list of options in our GraphQL schema.
  • Enums are useful for keeping data values consistent.

Up next

In the next lesson, we'll take a look at the input type: another tool for keeping schemas consistent.

Previous
Next