2. The enum type
5m

Overview

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

With a type like Int or String, a 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
  • See an example of how enums are used in the Airlock codebase

What is an enum?

An enum is a 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 .

Using what we know so far, we could define the locationType 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 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 's return type, the same way we would with any other or .

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

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

This means that when we 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 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 .
  • 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