# Boolean fields use descriptive prefixes

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

## Why it matters

A field named `active` could be a boolean, a verb, or a role descriptor — consumers can't tell from the name alone. `admin` is worse: it reads as a role name but is sometimes a boolean flag. When boolean fields lack `is_`/`has_`/`can_` prefixes, client code is forced to check documentation or source code before using the value, and TypeScript consumers may assign wrong types. iso-25010:2011 maintainability.readability is the direct impact: any developer reading the response must stop and verify semantics rather than inferring from the name.

## Severity rationale

Low because ambiguous boolean naming causes developer confusion and potential type bugs without enabling security exploits or data loss.

## Remediation

Add descriptive prefixes to all boolean fields so consumers can infer the type from the name without consulting documentation:

```json
// Before -- ambiguous field names:
{ "active": true, "admin": false, "verified": true }

// After -- intent is unambiguous:
{ "isActive": true, "isAdmin": false, "isVerified": true }
```

For snake_case APIs, prefer `is_active`, `has_permission`, `can_edit`. Apply the same prefix convention in your TypeScript interfaces, OpenAPI schema, and any serialization functions to keep all three in sync.

## Detection

- **ID:** `boolean-naming`
- **Severity:** `low`
- **What to look for:** Examine boolean fields in response objects across endpoints. Check whether boolean fields use descriptive prefixes that make the field's meaning unambiguous: `is_active`, `has_permission`, `can_edit`, `should_notify`, `was_deleted`. Look for ambiguous boolean names: `active` (is it a verb or adjective?), `admin` (is it a boolean or a role name?), `notification` (is it a boolean or an object?).
- **Pass criteria:** Count every boolean field across all response objects. Boolean fields consistently use `is_`/`has_`/`can_`/`should_`/`was_` prefixes (adapted to the API's casing convention: `isActive`, `hasPermission`, etc.). Fields are unambiguously boolean from their name alone. At least 90% of boolean fields must have descriptive prefixes.
- **Fail criteria:** Boolean fields use ambiguous names that could be confused with other types (e.g., `active`, `admin`, `verified`, `premium` without prefix). Multiple boolean fields across the API lack prefixes.
- **Skip (N/A) when:** No boolean fields found in any API response, or fewer than 2 boolean fields exist across all endpoints.
- **Detail on fail:** List the ambiguous boolean fields (e.g., "Boolean fields `active`, `admin`, `verified`, `premium` lack `is_`/`has_` prefixes. `admin` could be a role name, `verified` could be a timestamp. 4 of 6 boolean fields lack prefixes."). Max 500 chars.
- **Remediation:** Add descriptive prefixes to boolean fields so consumers can tell the type from the name alone:

  ```json
  // Before -- ambiguous:
  { "active": true, "admin": false, "verified": true }

  // After -- clear intent:
  { "isActive": true, "isAdmin": false, "isVerified": true }
  ```

  This is especially important for APIs consumed by teams who don't have access to the source code -- the field name is their only signal.

---

## External references

- iso-25010 maintainability.readability

Taxons: code-quality

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