Structured data explained

What is enum in JSON Schema, and why is it used?

A practical explanation of the enum keyword in JSON Schema: what it does, when to use it, how it interacts with const and type, and common pitfalls with clear examples.

By CheckMySchema editorial team · 2026-10-25

Minimal diagram of a C enum mapping enumerator names to integers on a midnight background with slate panels and cyan accents

Short answer: In JSON Schema, enum is a validation keyword that restricts a value to a fixed, finite set you provide. The value must equal one of those entries. The keyword takes an array of allowed values. The draft 2020-12 specification recommends a non-empty array with unique entries. Use it to enforce allowed options and improve data quality JSON Schema - Enumerated values.

This guide uses JSON Schema draft 2020-12 validation semantics. An empty enum array matches no instance; it is not a shortcut for allowing any value.

How enum works

Provide an array of allowed JSON values. Use a non-empty list with unique entries for a clear, maintainable schema; the draft 2020-12 specification expresses these as recommendations JSON Schema - Enumerated values.
Values can be any JSON type: string, number, boolean, null, object, or array. You can mix types if needed JSON Schema - Enumerated values.
You may omit type if you want to allow multiple types; add type when you want to constrain the instance’s type explicitly.

Basic example

{
  "type": "object",
  "properties": {
    "color": {
      "enum": ["red", "amber", "green"]
    }
  },
  "required": ["color"],
  "additionalProperties": false
}

Here, color must be one of red, amber, or green JSON Schema - Enumerated values.

Full frame minimalist editorial image showing a compact code snippet defining an enum for status and a switch statement with a simple blue cyan flow diagram

When to use enum (and when not)

Use enum when you have a closed list of acceptable values and you want validation to reject anything else. If you need exactly one fixed value, use const instead JSON Schema - Enumerated and constant values.

enum vs const

{
  "type": "object",
  "properties": {
    "state": { "enum": ["draft", "published", "archived"] },
    "version": { "const": 1 }
  }
}

When present, state must be one of the listed strings and version must equal the number 1. Neither property is required in this example because there is no required list JSON Schema - Enumerated and constant values.

Mixed types and practical modeling

You can enumerate values of different JSON types without declaring a type in the schema. This is useful for modeling special states like null.

{
  "type": "object",
  "properties": {
    "color": {
      "enum": ["red", "amber", "green", null, 42]
    }
  }
}

If you want to ensure only strings are allowed, add a type and keep enum values consistent with that type:

{
  "type": "object",
  "properties": {
    "color": {
      "type": "string",
      "enum": ["red", "amber", "green"]
    }
  }
}

For more about where JSON Schema fits in real projects, see What JSON Schema is used for in practice.

Labeling enum values for docs or UIs

The core enum keyword does not attach per-value descriptions or labels. A common pattern is to use oneOf (or anyOf) with const plus title/description on each branch so tools can display human-friendly option labels. This is a pattern used by tooling, not a change to enum itself GitHub discussion: Descriptions for each enum value.

{
  "type": "object",
  "properties": {
    "status": {
      "oneOf": [
        { "const": "D", "title": "Declined", "description": "The request was declined" },
        { "const": "A", "title": "Approved",  "description": "The request was approved" },
        { "const": "P", "title": "Pending",   "description": "Awaiting decision" }
      ]
    }
  }
}

Remember that oneOf means exactly one branch must match. Validators may show multiple branch errors when a value is invalid.

Minimal 2D vector diagram showing compiler assignment of enum values when some are explicit and others implicit with arrows indicating sequential value filling

Common pitfalls to avoid

Duplicate entries: remove redundant values for clarity. Do not claim that the draft 2020-12 meta-schema necessarily rejects duplicates; enum matching still checks membership in the listed values JSON Schema - Enumerated values.
Unintended types: if you omit type and mix values, you might accept a number or null unintentionally. Add type when you need a single kind of value.
Very large enums: consider alternate modeling (for example, pattern constraints or references to shared definitions) when the list is huge and changes frequently.

Redundant enum values: avoid this even if the schema is accepted

{
  "type": "object",
  "properties": {
    "priority": {
      "enum": ["low", "medium", "medium", "high"]
    }
  }
}

In draft 2020-12, duplicate values are discouraged but this is not a guaranteed schema-validation failure. A priority of "medium" still matches. Remove the duplicate rather than relying on a validator to reject the schema JSON Schema - Enumerated values.

Ship an enum safely

List the allowed values and confirm they are unique and complete.
Decide if you must constrain type (for example, type: "string") to prevent unintended types.
For human-friendly labels, use oneOf + const with title/description in tooling-facing schemas.
Add unit tests that try an invalid value to confirm rejection.
Document how to handle unknown or future values (for example, allow null or a fallback path if appropriate).

FAQ

Can enum include objects or arrays?

Yes. enum values can be any JSON value, including objects and arrays, as long as each is unique in the enum array JSON Schema - Enumerated values.

Do I need type with enum?

No. You can omit type and rely solely on enum. Add type when you want to restrict the instance to a single JSON type in addition to the enumerated values.

When should I use const instead of enum?

Use const when a property must have exactly one fixed value. Use enum when there are multiple allowed options JSON Schema - Enumerated and constant values.