# Enum values use consistent format

- **Pattern:** `ab-000354` (`api-design.naming-conventions.enum-naming`)
- **Severity:** medium
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000354
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000354)

## Why it matters

Magic numbers for status or type fields — `status: 1`, `role: 3` — are opaque to every consumer reading the response. Mixed enum formats across endpoints (SCREAMING_SNAKE on one, snake_case on another) mean consumers must maintain a lookup table per endpoint just to decode the same semantic concept. This directly violates iso-25010:2011 maintainability.modifiability: adding a new status value requires updating documentation, clients, and any code that pattern-matches on string values.

## Severity rationale

Medium because inconsistent enum formats create consumer confusion and maintenance overhead without enabling direct security exploitation.

## Remediation

Choose one enum format — `SCREAMING_SNAKE_CASE` is the REST convention for constants — and apply it globally. Replace magic numbers with readable strings:

```json
// Before -- inconsistent enums and magic numbers:
{ "status": "active", "role": 3, "plan": "PREMIUM" }

// After -- consistent SCREAMING_SNAKE throughout:
{ "status": "ACTIVE", "role": "ADMIN", "plan": "PREMIUM" }
```

Search your codebase for numeric values used as type discriminators (`status: 1`, `type: 2`) and replace them with string constants. Update your schema definitions and client-side switch statements in the same pass.

## Detection

- **ID:** `enum-naming`
- **Severity:** `medium`
- **What to look for:** Examine fields that represent fixed sets of values (status fields, type fields, role fields). Check whether enum values use a consistent format: `SCREAMING_SNAKE_CASE` ("PENDING", "IN_PROGRESS"), `snake_case` ("pending", "in_progress"), `kebab-case` ("pending", "in-progress"), or `camelCase` ("pending", "inProgress"). Also check: are enum values strings (good for readability) or magic numbers (bad -- `status: 1` tells the consumer nothing)?
- **Pass criteria:** Enumerate all enum-like fields (status, type, role, category, state) across every endpoint. Enum/constant values across the API use one consistent format with at least 90% using the same casing style. No magic numbers for status or type fields -- all use readable string values. Report the count of enum fields found and the format used by each.
- **Fail criteria:** Mixed enum formats across endpoints (e.g., `status: "ACTIVE"` in one endpoint, `type: "premium_user"` in another). Or magic numbers used for status/type fields (`status: 1`, `role: 3`). Quote the actual enum values found in each format.
- **Skip (N/A) when:** No enum-like fields found in any response (no status, type, role, or similar fixed-value fields).
- **Detail on fail:** Identify the inconsistency (e.g., "User status uses SCREAMING_SNAKE (`ACTIVE`, `SUSPENDED`) but order status uses lowercase (`pending`, `shipped`). Payment type uses magic numbers (`type: 1`, `type: 2`). 3 formats across 5 enum fields."). Max 500 chars.
- **Remediation:** Choose one format for all enum values and apply it globally. `SCREAMING_SNAKE_CASE` is the most common for API enums because it visually distinguishes constants from regular string values.

  ```json
  // Before -- inconsistent enums:
  { "status": "active", "role": 3, "plan": "PREMIUM" }

  // After -- consistent SCREAMING_SNAKE:
  { "status": "ACTIVE", "role": "ADMIN", "plan": "PREMIUM" }
  ```

## External references

- iso-25010 maintainability.modifiability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-000354