Enums

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
}

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.

Naming¶

Enum names and member names should use PascalCase.

enum PaymentStatus {
  Pending
  Completed
  Failed
}