Enum and Const — Fixed Value Validation

Enum and Const — Restricting to Fixed Values

The enum and const keywords restrict a value to a predefined set or a single literal. They are essential for fields with a known list of valid options.

enum — Multiple Allowed Values

{
  "enum": ["draft", "published", "archived"]
}

The value must be exactly one of the listed items. Comparison uses deep equality — strings must match exactly (case-sensitive), numbers must be identical, and objects/arrays use structural comparison.

const — Single Allowed Value

{
  "const": "2024-01-01"
}

The value must be exactly this one literal. const is equivalent to enum with a single element, but it expresses the intent more clearly and produces better error messages.

How the Example Schema Works

The schema demonstrates several patterns:

1. status — a string enum with five order statuses. Only these exact strings are accepted — "Shipped" (capitalized) would fail.

2. priority — a mixed-type enum accepting integers 1, 2, 3 or the string "urgent". JSON Schema enums can contain values of different types, unlike enums in most programming languages.

3. apiVersion — a const field pinned to "2024-01-01". This ensures requests are explicitly targeting a specific API version. When you release a new version, you update the const and clients must opt in.

4. currency — a string enum with ISO 4217 currency codes. Combining type: "string" with enum adds an extra layer of documentation, even though the enum values already imply the type.

5. isTest — const: false ensures this flag is always false in production schemas. Test environments use a separate schema with const: true.

Enum with Descriptions

Standard JSON Schema does not support per-value descriptions in enum. If you need labels or descriptions, use oneOf with const:

{
  "oneOf": [
    { "const": "pending", "title": "Pending", "description": "Order received, not yet processed" },
    { "const": "shipped", "title": "Shipped", "description": "Order dispatched to carrier" }
  ]
}

This pattern is recognized by documentation generators and form builders to display human-readable labels alongside enum values.

Case Sensitivity

JSON string comparison is case-sensitive. The enum ["USD", "EUR"] rejects "usd" and "eur". If you need case-insensitive matching, either normalize the input before validation or list all case variants (which is usually impractical).

Null in Enums

You can include null in an enum to create a nullable enum:

{ "enum": ["active", "inactive", null] }

This is a common pattern for status fields where null represents "not yet determined."