Enums in GraphQL
An enum type restricts a field or argument to one of a fixed, named set of values, declared with the enum keyword: enum Episode { NEWHOPE JEDI EMPIRE }. Unlike a String, an enum is validated by the GraphQL server itself — passing a value outside the declared set produces a validation error before execution even starts, and clients get compile-time or IDE-level autocomplete for the exact allowed values, which eliminates an entire class of typo bugs that plain string arguments are prone to.
Cricket analogy: A dismissal type in a scorecard is always one of a fixed set — bowled, caught, lbw, run out, stumped — never an arbitrary string, just as a GraphQL enum locks a field to a closed set of named values instead of free-form text.
Enum Values Across Language Boundaries
In the GraphQL SDL, enum values look like bare identifiers (NEWHOPE, not a string), but the exact runtime representation is up to the server implementation — a resolver in a JavaScript/TypeScript server, for instance, can map the SDL enum value NEWHOPE to an internal value like 4 via a custom value map, so the GraphQL-facing name and the internal representation don't have to match. This indirection is valuable when the underlying data source uses a different convention, such as legacy integer status codes, and it means renaming the wire-facing SDL enum value later doesn't require touching downstream database logic.
Cricket analogy: Broadcasters label a match state as 'Powerplay' on screen while the scoring system internally just tracks it as overs 1-6 with a fielding-restriction flag — the public label and the internal representation differ, just like a GraphQL enum value and its resolver-side mapping.
enum Episode {
NEWHOPE
EMPIRE
JEDI
}
type Movie {
id: ID!
title: String!
episode: Episode!
}
query {
movie(episode: EMPIRE) {
title
}
}Enums also work as input constraints — a mutation argument typed as an enum gets free server-side validation, rejecting any value outside the declared set with a clear GraphQL validation error, before your resolver code runs at all.
Adding a new enum value is usually a safe, additive schema change, but removing or renaming an existing enum value is breaking — any client still sending or expecting the old value will fail validation, so treat enum value removal with the same care as removing a field.
- Enums restrict a field or argument to a fixed, named set of values declared in the SDL.
- Invalid enum values are rejected by GraphQL's validation layer before execution starts.
- SDL enum value names are bare identifiers, distinct from the server's internal representation.
- Resolvers can map SDL enum names to different internal values (e.g. legacy integer codes).
- Enums used as arguments give free server-side validation on mutations and query inputs.
- Adding an enum value is additive and safe; removing or renaming one is a breaking change.
Practice what you learned
1. What happens when a client sends an enum argument value that isn't declared in the schema?
2. How are enum value names written in GraphQL SDL?
3. Why might a resolver map an SDL enum value to a different internal representation?
4. Which change to an existing enum is considered breaking?
5. What is one direct benefit of using an enum instead of a plain String for a status field?
Was this page helpful?
You May Also Like
The Type System In Depth
A deep dive into how GraphQL's schema — scalars, object types, input types, and list/non-null modifiers — forms the typed contract between client and server.
Nullable vs Non-Nullable Types
Why fields are nullable by default in GraphQL, what the `!` modifier guarantees, and how null bubbling propagates a single resolver failure up the response tree.
Interfaces and Unions
How GraphQL's two abstract types — interfaces with guaranteed shared fields, and unions with no shared contract — let a single field return polymorphic results.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics