What Enums Are

Enums define a named set of possible values.

enum OrderStatus {
  Pending
  Paid
  Shipped
}

Use enums when a field should accept only one value from a known list.

type Order {
  id string
  status OrderStatus
}

Implicit String Values

When a member has no explicit value, its value is the member name.

enum Status {
  Active
  Disabled
}

This is equivalent to:

enum Status {
  Active = "Active"
  Disabled = "Disabled"
}

Explicit String Values

Use explicit strings when the wire value should differ from the member name.

enum ProductStatus {
  Draft = "draft"
  Published = "published"
  Archived = "archived"
}

This is common when generated code should use nice member names while serialized data uses lowercase values.

Integer Enums

Enums can use integer values.

enum Priority {
  Low = 1
  Medium = 2
  High = 3
}

Integer values accept an optional leading minus with no space (e.g. Below = -1).

Values must fit in 64-bit signed range; out-of-range values are rejected.

For integer enums, every member must have an explicit integer value.

Invalid:

enum Priority {
  Low = 1
  Medium
  High = 3
}

Do Not Mix Value Kinds

An enum must be consistently string-based or integer-based.

Invalid:

enum MixedStatus {
  Active = "active"
  Disabled = 2
}

Unique Names And Values

Member names must be unique.

Invalid:

enum Status {
  Active
  Active = "active"
}

Member values must also be unique.

Invalid:

enum Status {
  Active = "enabled"
  Enabled = "enabled"
}

Enum Member Docstrings

enum InvoiceStatus {
  """ The invoice is editable and has not been sent. """
  Draft

  """ The invoice has been paid in full. """
  Paid
}

Enum Member Annotations

enum FeatureState {
  @deprecated("Use Enabled instead.")
  Active = "active"

  Enabled = "enabled"
}

Annotations on enum members are available to plugins.

Enum Spreads

Enums can reuse members from another enum with ...Name.

enum StandardRole {
  Viewer = "viewer"
  Editor = "editor"
}

enum WorkspaceRole {
  ...StandardRole
  Owner = "owner"
}

Enum spreads must reference another enum and must use the Name form, not Name.Member.

Every enum must declare at least one member, counting inherited spread members. An enum with no members is rejected.

Naming

Enum names and member names should use PascalCase.

enum PaymentStatus {
  Pending
  Completed
  Failed
}