# ENUM Ground Truth Reference — Mantara Schema Generator

This document is the authoritative source for ENUM classification in generated schemas.
When generating PostgreSQL ENUM types, the LLM MUST consult this file to select correct
values. Do NOT invent enum values that contradict this reference.

---

## A. Universal ENUMs

These ENUMs apply to ANY domain. When the schema requires one of these concepts,
use these exact values (adding or removing values only when the domain explicitly demands it).

### A.1 `status_enum`

General-purpose record status. Use when no domain-specific status enum exists.

```
draft, pending, active, inactive, suspended, cancelled, completed, archived
```

### A.2 `priority_enum`

Task or item priority ranking.

```
low, medium, high, critical, urgent
```

### A.3 `gender_enum`

Person gender classification.

```
male, female, non_binary, prefer_not_to_say, other
```

### A.4 `payment_method_enum`

Accepted payment instruments.

```
cash, credit_card, debit_card, bank_transfer, check, online_payment, mobile_payment
```

### A.5 `payment_status_enum`

Status of a payment transaction.

```
pending, processing, completed, failed, refunded, partially_refunded
```

### A.6 `approval_status_enum`

Approval workflow states.

```
pending, approved, rejected, revision_required
```

### A.7 `frequency_enum`

Recurrence interval for schedules, reports, or billing cycles.

```
daily, weekly, bi_weekly, monthly, quarterly, semi_annually, annually
```

### A.8 `day_of_week_enum`

Days of the week (ISO ordering).

```
monday, tuesday, wednesday, thursday, friday, saturday, sunday
```

### A.9 `address_type_enum`

Classification of physical addresses.

```
home, office, billing, shipping, warehouse
```

### A.10 `communication_type_enum`

Contact or communication channel.

```
email, phone, sms, in_person, video_call
```

### A.11 `document_type_enum`

File or document format classification.

```
pdf, docx, xlsx, image, other
```

### A.12 `user_role_enum`

Generic application access roles.

```
admin, manager, operator, viewer
```

### A.13 `notification_type_enum`

System notification classification.

```
alert, reminder, info, system
```

### A.14 `severity_enum`

Severity level for alerts, incidents, or issues.

```
info, warning, critical
```

### A.15 `transaction_type_enum`

Financial transaction direction.

```
income, expense
```

### A.16 `condition_enum`

Physical condition of an asset or item.

```
new, good, fair, needs_repair, out_of_service
```

---

## B. Domain-Specific ENUMs

Use these when the schema belongs to (or contains a module for) the listed domain.
Values are canonical defaults; adjust only when the user's description explicitly
calls for different values.

---

### B.1 Healthcare / Hospital

| ENUM Name | Values |
|-----------|--------|
| `blood_type_enum` | `a_positive, a_negative, b_positive, b_negative, ab_positive, ab_negative, o_positive, o_negative` |
| `appointment_status_enum` | `scheduled, confirmed, in_progress, completed, cancelled, no_show` |
| `ward_type_enum` | `general, private, semi_private, icu, nicu, maternity, pediatric, emergency, isolation` |
| `insurance_type_enum` | `private, government, employer, self_pay, military` |
| `prescription_status_enum` | `active, completed, cancelled, on_hold, expired` |
| `visit_type_enum` | `outpatient, inpatient, emergency, follow_up, telemedicine` |
| `diagnosis_severity_enum` | `mild, moderate, severe, critical, terminal` |
| `staff_role_enum` (healthcare) | `doctor, nurse, technician, pharmacist, administrative, support` |
| `department_enum` (healthcare) | `cardiology, neurology, orthopedics, pediatrics, oncology, radiology, pathology, general_medicine, surgery, emergency, ent, ophthalmology, dermatology, psychiatry` |

---

### B.2 Restaurant / Food Service

| ENUM Name | Values |
|-----------|--------|
| `order_status_enum` | `pending, confirmed, preparing, ready, served, completed, cancelled` |
| `order_type_enum` | `dine_in, takeaway, delivery` |
| `meal_type_enum` | `breakfast, lunch, dinner, snack, beverage, dessert` |
| `dietary_restriction_enum` | `none, vegetarian, vegan, gluten_free, nut_free, dairy_free, halal, kosher` |
| `table_status_enum` | `available, occupied, reserved, cleaning, out_of_service` |
| `reservation_status_enum` | `pending, confirmed, seated, completed, cancelled, no_show` |
| `cuisine_type_enum` | `italian, chinese, japanese, indian, mexican, thai, french, american, mediterranean, korean, middle_eastern, other` |
| `staff_role_enum` (restaurant) | `chef, sous_chef, waiter, bartender, host, manager, delivery, dishwasher` |

---

### B.3 Education / University

| ENUM Name | Values |
|-----------|--------|
| `enrollment_status_enum` | `enrolled, withdrawn, graduated, suspended, on_leave, deferred` |
| `grade_level_enum` | `freshman, sophomore, junior, senior, graduate, postgraduate` |
| `semester_enum` | `first_semester, second_semester, summer, winter` |
| `course_status_enum` | `active, inactive, archived, pending_approval` |
| `attendance_status_enum` | `present, absent, late, excused` |
| `assessment_type_enum` | `quiz, midterm, final_exam, assignment, project, presentation, lab_work, thesis` |
| `academic_standing_enum` | `good_standing, probation, academic_warning, dean_list, honors, dismissed` |
| `degree_level_enum` | `certificate, associate, bachelor, master, doctorate, postdoctoral` |
| `grade_enum` | `grade_a, grade_b, grade_c, grade_d, grade_f, incomplete, withdrawn, pass, fail` |

---

### B.4 E-commerce

| ENUM Name | Values |
|-----------|--------|
| `order_status_enum` | `pending, confirmed, processing, shipped, delivered, cancelled, returned` |
| `shipping_status_enum` | `label_created, picked_up, in_transit, out_for_delivery, delivered, failed_delivery, returned_to_sender` |
| `return_reason_enum` | `defective, wrong_item, not_as_described, changed_mind, arrived_late, damaged_in_shipping, other` |
| `product_condition_enum` | `new, refurbished, used_like_new, used_good, used_fair` |
| `delivery_method_enum` | `standard, express, overnight, same_day, pickup, freight` |
| `discount_type_enum` | `percentage, fixed_amount, buy_one_get_one, free_shipping` |
| `review_status_enum` | `pending, approved, rejected, flagged` |

---

### B.5 HR / Workforce Management

| ENUM Name | Values |
|-----------|--------|
| `employment_type_enum` | `full_time, part_time, contract, intern, freelance, temporary, seasonal` |
| `leave_type_enum` | `sick, vacation, personal, maternity, paternity, bereavement, unpaid, sabbatical, compensatory` |
| `leave_status_enum` | `pending, approved, rejected, cancelled` |
| `department_type_enum` | `engineering, sales, marketing, hr, finance, operations, legal, customer_support, executive, it, research` |
| `contract_type_enum` | `permanent, fixed_term, probationary, consultant, freelance` |
| `performance_rating_enum` | `outstanding, exceeds_expectations, meets_expectations, needs_improvement, unsatisfactory` |
| `employee_status_enum` | `active, on_leave, suspended, terminated, retired, resigned` |
| `payroll_frequency_enum` | `weekly, bi_weekly, semi_monthly, monthly` |

---

### B.6 Real Estate / Property Management

| ENUM Name | Values |
|-----------|--------|
| `property_type_enum` | `residential, commercial, industrial, land, mixed_use, agricultural` |
| `listing_status_enum` | `draft, active, under_contract, sold, expired, withdrawn` |
| `lease_type_enum` | `fixed_term, month_to_month, yearly, sublease` |
| `maintenance_priority_enum` | `low, medium, high, emergency` |
| `maintenance_status_enum` | `reported, assigned, in_progress, completed, deferred` |
| `property_condition_enum` | `excellent, good, fair, poor, under_renovation` |
| `tenant_status_enum` | `prospective, active, past_due, evicted, former` |

---

### B.7 Hotel / Hospitality

| ENUM Name | Values |
|-----------|--------|
| `room_type_enum` | `single, double, twin, suite, deluxe, presidential, dormitory, accessible` |
| `booking_status_enum` | `pending, confirmed, checked_in, checked_out, cancelled, no_show` |
| `room_status_enum` | `available, occupied, reserved, maintenance, out_of_order` |
| `guest_type_enum` | `walk_in, reservation, group, corporate, loyalty_member, vip` |
| `housekeeping_status_enum` | `clean, dirty, in_progress, inspected, out_of_service` |
| `amenity_type_enum` | `wifi, parking, pool, gym, spa, restaurant, room_service, laundry, concierge, minibar` |

---

### B.8 Construction / Project Management

| ENUM Name | Values |
|-----------|--------|
| `project_phase_enum` | `planning, design, permitting, procurement, construction, inspection, handover, warranty, closed` |
| `material_type_enum` | `concrete, steel, lumber, electrical, plumbing, finishing, roofing, insulation, glass, hardware` |
| `worker_role_enum` | `supervisor, foreman, electrician, plumber, carpenter, mason, welder, laborer, crane_operator, safety_officer` |
| `inspection_status_enum` | `scheduled, in_progress, passed, failed, conditional_pass, reinspection_required` |
| `budget_category_enum` | `labor, materials, equipment, subcontractor, permits, overhead, contingency, professional_fees` |
| `milestone_status_enum` | `planned, in_progress, completed, delayed, at_risk` |
| `change_order_status_enum` | `proposed, under_review, approved, rejected, implemented` |

---

### B.9 Agriculture / Farm Management

| ENUM Name | Values |
|-----------|--------|
| `crop_type_enum` | `cereal, pulse, oilseed, vegetable, fruit, spice, fiber, fodder` |
| `soil_type_enum` | `clay, sandy, loam, silt, peat, chalk, alluvial, black_cotton, red, laterite` |
| `irrigation_method_enum` | `drip, sprinkler, surface, flood, furrow, center_pivot, manual` |
| `harvest_status_enum` | `planned, in_progress, completed, delayed, lost` |
| `storage_type_enum` | `silo, warehouse, cold_storage, open_yard, granary` |
| `growth_stage_enum` | `germination, seedling, vegetative, flowering, fruiting, harvest, dormant` |
| `plot_status_enum` | `cultivated, fallow, prepared, harvested, under_maintenance` |
| `season_enum` | `spring, summer, autumn, winter, wet_season, dry_season` |
| `livestock_species_enum` | `cattle, buffalo, goat, sheep, poultry, pig, horse, fish` |
| `quality_grade_enum` | `grade_a, grade_b, grade_c, rejected` |

---

### B.10 Logistics / Supply Chain

| ENUM Name | Values |
|-----------|--------|
| `shipment_status_enum` | `pending, dispatched, in_transit, at_hub, out_for_delivery, delivered, returned, lost` |
| `vehicle_type_enum` | `truck, van, motorcycle, bicycle, drone, ship, rail` |
| `warehouse_zone_enum` | `receiving, storage, picking, packing, shipping, returns, cold_chain, hazardous` |
| `inventory_movement_enum` | `inbound, outbound, transfer, adjustment, return, scrap` |

---

### B.11 Legal / Compliance

| ENUM Name | Values |
|-----------|--------|
| `case_status_enum` | `open, in_progress, on_hold, settled, dismissed, closed, appealed` |
| `document_status_enum` | `draft, under_review, approved, signed, executed, expired, revoked` |
| `compliance_status_enum` | `compliant, non_compliant, pending_review, remediation_in_progress, exempt` |

---

## C. Column Name to ENUM Mapping Rules

When the LLM encounters a column name, use this mapping to decide which ENUM type to apply.
The `<context>` placeholder means the ENUM name should reflect the business domain
(e.g., `order_status_enum`, `appointment_status_enum`).

| Column Name Pattern | ENUM to Use | Example |
|---------------------|-------------|---------|
| `*_status` | `<context>_status_enum` | `order_status` -> `order_status_enum` |
| `*_type` | `<context>_type_enum` | `room_type` -> `room_type_enum` |
| `*_role` | `<context>_role_enum` | `staff_role` -> `staff_role_enum` |
| `*_category` | `<context>_category_enum` | `budget_category` -> `budget_category_enum` |
| `*_priority` | `priority_enum` | `task_priority` -> `priority_enum` |
| `*_severity` | `severity_enum` | `alert_severity` -> `severity_enum` |
| `*_level` | `<context>_level_enum` | `grade_level` -> `grade_level_enum` |
| `*_method` | `<context>_method_enum` | `payment_method` -> `payment_method_enum` |
| `*_mode` | `<context>_mode_enum` | `delivery_mode` -> `delivery_mode_enum` |
| `*_phase` | `<context>_phase_enum` | `project_phase` -> `project_phase_enum` |
| `*_stage` | `<context>_stage_enum` | `growth_stage` -> `growth_stage_enum` |
| `*_frequency` | `frequency_enum` | `billing_frequency` -> `frequency_enum` |
| `*_condition` | `<context>_condition_enum` | `product_condition` -> `product_condition_enum` |
| `*_rating` | `<context>_rating_enum` | `performance_rating` -> `performance_rating_enum` |
| `gender` | `gender_enum` | always use universal `gender_enum` |
| `blood_type` | `blood_type_enum` | always use healthcare `blood_type_enum` |
| `day_of_week` / `weekday` | `day_of_week_enum` | always use universal `day_of_week_enum` |
| `payment_method` | `payment_method_enum` | always use universal `payment_method_enum` |
| `payment_status` | `payment_status_enum` | always use universal `payment_status_enum` |

### Priority Order

When a column could match multiple rules:

1. **Exact match** in universal ENUMs takes precedence (e.g., `gender` always uses `gender_enum`).
2. **Domain-specific** match from Section B takes precedence over generic pattern match.
3. **Pattern match** from the table above is the fallback.

---

## D. Anti-Patterns

These are common mistakes. The LLM MUST NOT produce any of the following.

### D.1 Using VARCHAR for Controlled Values

**WRONG:**
```sql
status VARCHAR(20) DEFAULT 'active'
```

**CORRECT:**
```sql
status <schema>.status_enum DEFAULT 'active'
```

Rule: If a column has a finite, known set of valid values, it MUST be an ENUM type, not VARCHAR.

### D.2 Two-Value ENUMs (Use BOOLEAN Instead)

**WRONG:**
```sql
CREATE TYPE schema.active_enum AS ENUM ('active', 'inactive');
CREATE TYPE schema.yes_no_enum AS ENUM ('yes', 'no');
CREATE TYPE schema.visibility_enum AS ENUM ('visible', 'hidden');
```

**CORRECT:**
```sql
is_active BOOLEAN DEFAULT TRUE
is_visible BOOLEAN DEFAULT TRUE
```

Rule: If an ENUM would have exactly 2 values that represent a true/false condition, use `BOOLEAN` instead.
Exception: If the two values are not semantically boolean (e.g., `male/female` is NOT a boolean), keep the ENUM.

### D.3 Oversized ENUMs (Use a Lookup Table Instead)

**WRONG:**
```sql
CREATE TYPE schema.country_enum AS ENUM ('afghanistan', 'albania', ... /* 195 values */);
CREATE TYPE schema.product_category_enum AS ENUM (/* 25+ values */);
```

**CORRECT:**
```sql
CREATE TABLE schema.countries (
    id SERIAL PRIMARY KEY,
    code VARCHAR(3) NOT NULL UNIQUE,
    name VARCHAR(255) NOT NULL
);
```

Rule: If an ENUM would have more than 15 values, or if the values need to be user-configurable, use a lookup/reference table with a foreign key instead.

### D.4 Generic or Meaningless Values

**WRONG:**
```sql
CREATE TYPE schema.type_enum AS ENUM ('type1', 'type2', 'type3');
CREATE TYPE schema.category_enum AS ENUM ('a', 'b', 'c');
CREATE TYPE schema.status_enum AS ENUM ('status_one', 'status_two');
```

**CORRECT:**
```sql
CREATE TYPE schema.order_type_enum AS ENUM ('dine_in', 'takeaway', 'delivery');
```

Rule: Every ENUM value must be a meaningful, domain-relevant term. Never use placeholder or numbered values.

### D.5 Inconsistent Casing

**WRONG:**
```sql
CREATE TYPE schema.status_enum AS ENUM ('Active', 'In Progress', 'COMPLETED');
CREATE TYPE schema.type_enum AS ENUM ('Type-A', 'type_b', 'TYPE C');
```

**CORRECT:**
```sql
CREATE TYPE schema.status_enum AS ENUM ('active', 'in_progress', 'completed');
```

Rule: ALL enum values MUST be `snake_case` — lowercase letters, digits, and underscores only.
No spaces, hyphens, slashes, capital letters, or special characters.

### D.6 Duplicate or Overlapping ENUMs

**WRONG:**
```sql
CREATE TYPE schema.status_enum AS ENUM ('active', 'inactive', 'pending');
CREATE TYPE schema.record_status_enum AS ENUM ('active', 'inactive', 'archived');
-- Two ENUMs with overlapping values used for the same concept
```

**CORRECT:**
```sql
CREATE TYPE schema.status_enum AS ENUM ('active', 'inactive', 'pending', 'archived');
-- One ENUM, reused across columns that share the same concept
```

Rule: Do not create multiple ENUMs for the same conceptual domain. If two columns represent
the same kind of status, they should share one ENUM type. Create separate ENUMs only when the
value sets are genuinely different (e.g., `order_status_enum` vs `payment_status_enum`).

### D.7 Missing Context in ENUM Names

**WRONG:**
```sql
CREATE TYPE schema.status_enum AS ENUM (...);  -- which status?
CREATE TYPE schema.type_enum AS ENUM (...);    -- type of what?
```

**CORRECT:**
```sql
CREATE TYPE schema.order_status_enum AS ENUM (...);
CREATE TYPE schema.room_type_enum AS ENUM (...);
```

Rule: ENUM type names must include the business context. The only exception is truly universal
ENUMs (like `gender_enum`, `priority_enum`, `day_of_week_enum`) where the name is
self-explanatory.

### D.8 Using ENUM for Numeric Ranges

**WRONG:**
```sql
CREATE TYPE schema.age_range_enum AS ENUM ('0_17', '18_25', '26_35', '36_50', '51_plus');
CREATE TYPE schema.price_tier_enum AS ENUM ('under_10', '10_to_50', '50_to_100', 'over_100');
```

**CORRECT:** Use `NUMERIC` or `INT` columns with `CHECK` constraints, or a lookup table with
`min_value` / `max_value` columns.

### D.9 ENUM Values That Contain Units or Formatting

**WRONG:**
```sql
CREATE TYPE schema.weight_enum AS ENUM ('5kg', '10kg', '25kg');
CREATE TYPE schema.duration_enum AS ENUM ('30_minutes', '1_hour', '2_hours');
```

**CORRECT:** Use a `NUMERIC` column with an appropriate unit comment.
```sql
weight_kg NUMERIC(10,2) NOT NULL, -- in kilograms
duration_minutes INT NOT NULL     -- in minutes
```

---

## E. Validation Checklist

Before finalizing any schema, verify:

- [ ] Every column ending in `_status`, `_type`, `_role`, `_method`, `_category`, `_phase`, or `_mode` uses a proper ENUM type
- [ ] No VARCHAR columns are used where an ENUM would be appropriate
- [ ] No ENUM has fewer than 3 values (consider BOOLEAN) — exception: non-boolean pairs
- [ ] No ENUM has more than 15 values (consider a lookup table)
- [ ] All ENUM values are snake_case with no special characters
- [ ] All ENUM type names follow `<schema>.<descriptive_name>_enum` convention
- [ ] Universal ENUMs (gender, payment_method, day_of_week) use the canonical values from Section A
- [ ] Domain-specific ENUMs use values from Section B when the domain matches
- [ ] No duplicate or overlapping ENUMs exist for the same concept
- [ ] ENUM names include business context (not bare `status_enum` or `type_enum`)