GraphQL Enum Types

An enum type defines a set of allowed string values for a field. When a field can only ever be one of a few specific options, an enum makes that contract explicit in the schema. Clients know exactly what values are valid, and the server rejects anything outside the list.

The Problem Enums Solve

Imagine an order status field defined as a plain String. The client might send "pending", "PENDING", "Pending", or "waiting" — all meaning the same thing but breaking the server logic. An enum prevents this by locking the allowed values.

  Without enum:             With enum:
  ─────────────             ──────────
  status: String            enum OrderStatus {
                              PENDING
  Client can send:            PROCESSING
  "pending"                   SHIPPED
  "Pending"                   DELIVERED
  "waiting"                   CANCELLED
  "in-transit"              }
  (chaos)
                            status: OrderStatus
                            (only 5 valid values)

Defining an Enum

  enum Direction {
    NORTH
    SOUTH
    EAST
    WEST
  }

  type Traveler {
    name:      String!
    heading:   Direction!
  }

Enum values are written in uppercase by convention, though GraphQL does not enforce this.

Using an Enum in a Query

Enum values in queries are written without quotes. They look like keywords, not strings.

  Schema:
  ────────
  enum Season { SPRING SUMMER AUTUMN WINTER }

  type Query {
    events(season: Season!): [Event]
  }

  Query:
  ───────
  {
    events(season: SUMMER) {    ← No quotes around SUMMER
      name
      date
    }
  }

  ✗ Invalid — enums do not use quotes in query literals:
  ──────────────────────────────────────────────────────
  events(season: "SUMMER") { ... }   ← Error

Enum in a Response

When an enum field appears in a response, GraphQL serializes it as a string. The client receives the enum value name as plain text.

  Internal representation:    JSON response:
  ────────────────────────    ──────────────
  OrderStatus.SHIPPED     →   "status": "SHIPPED"

Traffic Light Example

  enum TrafficLight {
    RED
    YELLOW
    GREEN
  }

  type Intersection {
    id:      ID!
    address: String!
    signal:  TrafficLight!
  }

  Query:
  ───────
  {
    intersection(id: "5th-Main") {
      address
      signal
    }
  }

  Response:
  ──────────
  {
    "intersection": {
      "address": "5th Main & MG Road",
      "signal": "GREEN"
    }
  }

Enums as Sort Orders

Enums work well for sort and filter options where a fixed set of choices applies.

  enum ProductSort {
    PRICE_LOW_TO_HIGH
    PRICE_HIGH_TO_LOW
    NEWEST_FIRST
    BEST_RATED
  }

  type Query {
    products(sort: ProductSort = NEWEST_FIRST): [Product]
  }

Key Points

• Enums restrict a field to a fixed list of allowed values.
• Enum values are uppercase by convention and written without quotes in query literals.
• The server validates enum arguments before running any resolver, rejecting invalid values immediately.
• Enums work as both field types and argument types, making them useful for filters, sorts, and status fields.