GraphQL Enum Types — Defining Fixed Sets of Allowed Values

In this tutorial, you will learn about Graphql Enum Types. We cover key concepts, practical examples, and best practices to help you master this topic.

GraphQL enum types define a fixed set of allowed string values for a field, providing type safety, auto-completion, and validation compared to using plain strings.

What You'll Learn

• Defining enum types in SDL
• Using enums in queries and mutations
• Mapping enums to internal values

Why It Matters

Enums prevent invalid values, improve API documentation, and enable client auto-completion. Using strings instead of enums leads to runtime errors from typos.

Code Examples

# Enum type definitions
enum Role {
  USER
  ADMIN
  MODERATOR
  SUPER_ADMIN
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
  DELETED
}

enum SortOrder {
  ASC
  DESC
}

enum Color {
  RED
  GREEN
  BLUE
  @deprecated(reason: "Use hex codes instead")
}

type User {
  id: ID!
  name: String!
  role: Role!
  status: PostStatus!
}

type Query {
  users(role: Role, sort: SortOrder = ASC): [User!]!
  posts(status: PostStatus): [Post!]!
}

// Enum resolvers with internal mapping
const typeDefs = `
  enum Role {
    USER
    ADMIN
    MODERATOR
  }
`;

const resolvers = {
  Role: {
    USER: 'user',
    ADMIN: 'admin',
    MODERATOR: 'moderator'
  }
};

// Usage in query resolver
const queryResolvers = {
  users: (parent, { role }, { db }) => {
    if (role) {
      // role value is the internal mapped value
      return db.users.findByRole(role);
    }
    return db.users.findAll();
  }
};

# Python enum type with Strawberry
import strawberry
from enum import Enum

class Role(str, Enum):
    USER = 'user'
    ADMIN = 'admin'
    MODERATOR = 'moderator'

@strawberry.enum
class PostStatus(Enum):
    DRAFT = 'draft'
    PUBLISHED = 'published'
    ARCHIVED = 'archived'

@strawberry.type
class User:
    id: strawberry.ID
    name: str
    role: Role

Common Mistakes

1. Using Strings Instead of Enums

Strings allow any value. Enums restrict to valid values and enable tooling.

2. Changing Enum Values

Once published, enum values should not be removed or renamed. Add new values only.

3. Not Using Enums for Status Fields

Status fields with a fixed set of values should always be enums.

4. Using Enums for Dynamic Value Sets

Enums are for fixed sets. For dynamic values, use scalars with validation.

5. Making Enum Names Too Generic

Use descriptive names like PostStatus instead of Status to avoid ambiguity.

Practice Questions

1. What is the purpose of enum types?
2. How do you map GraphQL enums to internal values?
3. Can enum values contain spaces or special characters?
4. What happens if you try to use an invalid enum value?
5. How do you deprecate an enum value?

Answers:

1. To define a fixed set of allowed string values for type safety.
2. By providing a resolver map from GraphQL value to internal value.
3. No. Enum values must be valid identifiers (alphanumeric, underscore).
4. GraphQL returns a validation error for invalid enum values.
5. Use the @deprecated directive on the enum value.

Challenge: Design enums for a video streaming platform: VideoQuality (SD, HD, FHD, UHD), SubscriptionTier (FREE, BASIC, PREMIUM, ENTERPRISE), ContentRating (G, PG, PG13, R, NC17), and PlaybackSpeed (0_5, 1_0, 1_25, 1_5, 2_0).

FAQ

Mini Project

Build a complete enum system for an e-commerce platform with OrderStatus, PaymentMethod, ShippingMethod, ProductCategory, and DiscountType enums. Include internal value mappings, deprecated values, and validation tests.

What's Next

Explore interface types for shared field definitions, then learn about union types for polymorphic responses.