Enums

Enums restrict a value to a predefined set.

API-Level Enum

Enums at the API level are shared across contracts:

Apiwork::API.define '/api/v1' do
  enum :status, values: %w[draft published archived]

  resources :posts
end

Contract-Scoped Enum

Enums inside a contract are scoped to local use:

class PostContract < Apiwork::Contract::Base
  enum :status, values: %w[draft published archived]

  object :post do
    uuid :id
    string :title
    string :status, enum: :status
  end
end

Using Enums

In Params

A defined enum is referenced by name:

string :status, enum: :status

Inline Validation

Without defining a separate enum:

string :status, enum: %w[draft published archived]

Enum Metadata

enum :status,
     values: %w[draft published archived],
     description: 'Publication status',
     example: 'published',
     deprecated: false

Generated Output

Introspection

{
  "status": {
    "values": ["draft", "published", "archived"],
    "description": "Publication status",
    "example": "published"
  }
}

TypeScript

export type Status = 'archived' | 'draft' | 'published';

Zod

export const StatusSchema = z.enum(['archived', 'draft', 'published']);

OpenAPI

Status:
  type: string
  enum: [draft, published, archived]
  description: Publication status
  example: published

See also

• Contract::Base reference — enum method