feat: add flattened errors for API consumption

- Add getFlattenedErrors() instance method on ValidationException
- Add ValidationException::flattenErrors() static method for tryValidate() results
- Implement '_root' namespace for root-level errors, dot notation for nested fields
- Add comprehensive test coverage (15 test cases)
- Update documentation with usage examples and API reference
- Update CHANGELOG, ROADMAP, TASKS, and README

Author: lemmon

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+- `getFlattenedErrors()` method on `ValidationException` returning a flattened list of errors suitable for API consumption. Each error entry contains `path` (field path with `'_root'` for root-level errors) and `message` (error message). Supports nested structures, array items, and maintains consistent path notation.
+- `ValidationException::flattenErrors()` static method for flattening errors from `tryValidate()` results without needing to catch exceptions. Returns empty array when passed `null`.
+
 ## [0.10.0] - 2025-12-10
 
 ### Added

README.md

@@ -30,6 +30,7 @@ Rather than reimplementing every possible transformation or validation rule, Lem
 - **Form Safety First**: Empty strings coerce to `null` (not dangerous `0`/`false`) to prevent real-world issues like accidental zero bank balances
 - **Fluent API with Execution Order Guarantee**: Validation rules read like natural language and execute in the exact order written -- `Validator::isString()->pipe('trim')->nullifyEmpty()->required()`
 - **Comprehensive Error Collection**: All validation errors are collected, not just the first failure
+- **API-Friendly Error Format**: Flattened errors with field paths (`'_root'` for root-level, dot notation for nested) perfect for frontend consumption
 - **Type-Aware Transformations**: Intelligent transformation system that maintains type context and handles coercion automatically
 - **Extensible Architecture**: Generic transformation methods work with any PHP callable or external library
 - **Strict Typing**: All files use `declare(strict_types=1);`, so scalar mismatches raise clear errors; opt into `coerce()` when you need form-friendly conversions.
@@ -41,6 +42,7 @@ Rather than reimplementing every possible transformation or validation rule, Lem
 - **Type-safe validation** for strings, integers, floats, arrays, and objects
 - **Fluent, chainable API** with guaranteed execution order -- methods execute exactly as written in the chain
 - **Comprehensive error collection** with detailed, structured feedback
+- **API-friendly flattened errors** with field paths for easy frontend integration (`getFlattenedErrors()`, `ValidationException::flattenErrors()`)
 - **Intuitive custom validation** with `satisfies()` method and optional error messages
 - **Logical combinators** (`Validator::allOf()`, `Validator::anyOf()`, `Validator::not()`) for complex validation logic
 - **Form-safe coercion** - empty strings become `null` (not dangerous `0`/`false`) for real-world safety
@@ -71,9 +73,18 @@ $userSchema = Validator::isAssociative([
 
 // Tuple-based validation (no exceptions)
 [$valid, $user, $errors] = $userSchema->tryValidate($input);
+if (!$valid) {
+    $flattened = \Lemmon\Validator\ValidationException::flattenErrors($errors);
+    // Returns: [['path' => 'name', 'message' => 'Value is required'], ...]
+}
 
 // Exception-based validation
-$user = $userSchema->validate($input); // Throws ValidationException on failure
+try {
+    $user = $userSchema->validate($input);
+} catch (\Lemmon\Validator\ValidationException $e) {
+    $flattened = $e->getFlattenedErrors();
+    // Returns: [['path' => 'name', 'message' => 'Value is required'], ...]
+}
 ```
 
 ## Documentation

ROADMAP.md

@@ -10,7 +10,14 @@ This roadmap outlines the strategic development plan for future releases, priori
 
 ## Recently Completed
 
-### String Validators Bundle & Array Enhancements (Current)
+### Flattened Errors for API Consumption (Current)
+- [x] **Flattened Error Response** - Added `getFlattenedErrors()` method on `ValidationException` returning API-friendly error format
+- [x] **Static Flatten Method** - Added `ValidationException::flattenErrors()` static method for use with `tryValidate()` results
+- [x] **Path Convention** - Implemented `'_root'` namespace for root-level errors, dot notation for nested fields, index notation for arrays
+- [x] **Comprehensive Documentation** - Added complete guide section with examples for both exception and tuple-based patterns
+- [x] **Full Test Coverage** - Added 15 test cases covering all validation scenarios and edge cases
+
+### String Validators Bundle & Array Enhancements
 - [x] **String Format Validators** - Added `hostname()`, `time()`, `base64()`, `hex()`, `domain()`, and `regex()` alias
 - [x] **Enum-Based Variant Flags** - Implemented `IpVersion`, `Base64Variant`, and `UuidVariant` enums for type-safe variant selection
 - [x] **UUID v7 Support** - Added support for UUID version 7 (Unix timestamp-based, sortable)
@@ -291,8 +298,8 @@ $stringValidator = Validator::isString()
 - ~~`when(condition, transform)`~~ -- Complex conditional logic, use external control flow
 
 ### Enhanced Error Handling
+- [x] **Error path enhancement** - Full field paths for nested validation errors (flattened errors with `'_root'` namespace)
 - [ ] **Structured error codes** - Programmatic error identification
-- [ ] **Error path enhancement** - Full field paths for nested validation errors
 
 ### Real-World Validation Gaps (For Consideration)
 - [ ] **`notEmpty()` method** - Explicit validation that value is not empty string/array (clearer than custom validation)

TASKS.md

@@ -2,14 +2,23 @@
 
 Public repo; keep this list short (about 7) and up to date. Rules: no numbering (keeps churn low), prune completed items, and replace them with the next priority. Contributors: pick one task, keep PRs focused, and update the list as things land.
 
-- Universal enum/const
-  - Add `enum()` and `const()` validators available on all types; cover mixed scalar inputs and document usage.
+- Universal enum/const validators
+  - Add `enum()` and `const()` methods available on all validator types; handle mixed scalar inputs and document usage patterns.
 
-- Error metadata
-  - Introduce structured error codes and enhanced error paths for nested schemas; keep backward compatibility for existing error shapes.
+- Structured error codes
+  - Add programmatic error codes to validation errors (e.g., 'STRING_TOO_SHORT', 'INVALID_EMAIL') for better error handling and i18n support; keep backward compatibility.
+
+- `in()` alias for `oneOf()`
+  - Add `in()` method as an alias for `oneOf()` for more intuitive API (`->in(['active', 'inactive'])` reads better than `->oneOf()`).
+
+- `between()` convenience methods
+  - Add `between(min, max)` shorthand for strings (length) and numerics (range) to reduce boilerplate (`->between(3, 50)` vs `->minLength(3)->maxLength(50)`).
+
+- `notEmpty()` validation method
+  - Add explicit `notEmpty()` method for validating non-empty strings/arrays; clearer than custom validation for common use case.
 
 - Mutation testing pilot
-  - Wire Infection (or similar) to the suite, add baseline config, and document how to run it locally.
+  - Wire Infection (or similar) to the test suite, add baseline config, and document how to run it locally for enhanced test quality verification.
 
 - Property-based tests
-  - Add a small property-based test set for key validators (string patterns, numeric constraints) to harden edge cases.
+  - Add a small property-based test set for key validators (string patterns, numeric constraints) to harden edge cases and catch regressions.

docs/guides/error-handling.md

@@ -62,6 +62,92 @@ try {
 }
 ```
 
+## Flattened Errors for API Consumption
+
+For API responses, you often need a flat list of errors with field paths. The `ValidationException` class provides methods to convert nested error structures into a flattened format suitable for frontend consumption.
+
+### Using getFlattenedErrors() with Exceptions
+
+When catching a `ValidationException`, use `getFlattenedErrors()` to get a flattened list:
+
+```php
+use Lemmon\Validator\ValidationException;
+
+try {
+    $schema->validate($input);
+} catch (ValidationException $e) {
+    $flattened = $e->getFlattenedErrors();
+    // Returns: [
+    //     ['path' => 'name', 'message' => 'Value is required'],
+    //     ['path' => 'email', 'message' => 'Value must be a valid email address'],
+    //     ['path' => 'user.profile.phone', 'message' => 'Invalid phone format']
+    // ]
+}
+```
+
+### Using flattenErrors() with tryValidate()
+
+When using `tryValidate()` (which doesn't throw exceptions), use the static `flattenErrors()` method:
+
+```php
+use Lemmon\Validator\ValidationException;
+
+[$valid, $data, $errors] = $validator->tryValidate($input);
+
+if (!$valid) {
+    $flattened = ValidationException::flattenErrors($errors);
+    // Returns empty array if $errors is null
+    // Otherwise returns same format as getFlattenedErrors()
+}
+```
+
+### Error Path Convention
+
+- **Root-level errors**: Use `'_root'` path for scalar validator errors and container type errors
+- **Field paths**: Use dot notation for nested fields (e.g., `'user.profile.email'`)
+- **Array items**: Use index notation (e.g., `'items.0'`, `'items.1'`)
+
+### Example: API Response Format
+
+```php
+try {
+    $schema->validate($input);
+    return ['success' => true, 'data' => $validated];
+} catch (ValidationException $e) {
+    return [
+        'success' => false,
+        'errors' => $e->getFlattenedErrors()
+    ];
+}
+```
+
+JSON output example:
+```json
+{
+  "success": false,
+  "errors": [
+    {"path": "name", "message": "Value is required"},
+    {"path": "email", "message": "Value must be a valid email address"},
+    {"path": "user.profile.phone", "message": "Invalid phone format"}
+  ]
+}
+```
+
+### Example: Root-Level Errors
+
+For scalar validators or container type errors:
+
+```php
+try {
+    Validator::isString()->email()->validate('invalid');
+} catch (ValidationException $e) {
+    $flattened = $e->getFlattenedErrors();
+    // Returns: [
+    //     ['path' => '_root', 'message' => 'Value must be a valid email address']
+    // ]
+}
+```
+
 ## Comprehensive Error Collection
 
 Unlike many validators that stop at the first error, Lemmon Validator collects **all** validation errors:

docs/guides/object-validation.md

@@ -431,6 +431,34 @@ if (!$valid) {
 }
 ```
 
+### Flattened Errors for API Responses
+
+For API consumption, you can flatten the nested error structure:
+
+```php
+use Lemmon\Validator\ValidationException;
+
+// With exceptions
+try {
+    $schema->validate($input);
+} catch (ValidationException $e) {
+    $flattened = $e->getFlattenedErrors();
+    // Returns: [
+    //     ['path' => 'name', 'message' => 'Value is required'],
+    //     ['path' => 'user.profile.email', 'message' => 'Value must be a valid email address']
+    // ]
+}
+
+// With tryValidate
+[$valid, $data, $errors] = $schema->tryValidate($input);
+if (!$valid) {
+    $flattened = ValidationException::flattenErrors($errors);
+    // Same format as above
+}
+```
+
+See the [Error Handling Guide](../guides/error-handling.md#flattened-errors-for-api-consumption) for complete documentation on flattened errors.
+
 ## Advanced Examples
 
 ### Multi-Step Form Validation

src/Lemmon/Validator/StringValidator.php

@@ -217,8 +217,7 @@ public function base64(
                 Base64Variant::Standard => preg_match('/^[A-Za-z0-9+\/]*={0,2}$/', $value) === 1
                     && ($decoded = base64_decode($value, true)) !== false
                     && base64_encode($decoded) === $value,
-                Base64Variant::UrlSafe => // Try standard Base64 first // URL-safe parsers accept both standard and URL-safe variants
-                preg_match('/^[A-Za-z0-9+\/]*={0,2}$/', $value) === 1
+                Base64Variant::UrlSafe => preg_match('/^[A-Za-z0-9+\/]*={0,2}$/', $value) === 1 // Try standard Base64 first // URL-safe parsers accept both standard and URL-safe variants
                 && ($decoded = base64_decode($value, true)) !== false
                 && base64_encode($decoded) === $value
                     // Or try URL-safe Base64

src/Lemmon/Validator/ValidationException.php

@@ -23,4 +23,141 @@ public function getErrors(): array
     {
         return $this->errors;
     }
+
+    /**
+     * Returns a flattened list of errors suitable for API consumption.
+     *
+     * Each error entry contains:
+     * - 'path': Field path ('_root' for root-level scalar/container errors, '_global' reserved for future cross-field validation)
+     * - 'message': Error message
+     *
+     * @return array<int, array{path: string, message: string}>
+     */
+    public function getFlattenedErrors(): array
+    {
+        return self::flattenErrors($this->errors);
+    }
+
+    /**
+     * Flattens an error array structure into a list suitable for API consumption.
+     *
+     * Useful for flattening errors from `tryValidate()` results:
+     * ```php
+     * [$valid, $data, $errors] = $validator->tryValidate($value);
+     * if (!$valid) {
+     *     $flattened = ValidationException::flattenErrors($errors);
+     * }
+     * ```
+     *
+     * Each error entry contains:
+     * - 'path': Field path ('_root' for root-level scalar/container errors, '_global' reserved for future cross-field validation)
+     * - 'message': Error message
+     *
+     * @param array<array-key, mixed>|null $errors The error structure to flatten (null returns empty array)
+     * @return array<int, array{path: string, message: string}>
+     */
+    public static function flattenErrors(null|array $errors): array
+    {
+        if ($errors === null) {
+            return [];
+        }
+
+        return self::flattenErrorsRecursive($errors, '');
+    }
+
+    /**
+     * Recursively flattens nested error structure into a list of path/message pairs.
+     *
+     * @param array<array-key, mixed> $errors The error structure to flatten
+     * @param string $basePath The base path prefix for building full paths
+     * @return array<int, array{path: string, message: string}>
+     */
+    private static function flattenErrorsRecursive(array $errors, string $basePath): array
+    {
+        $result = [];
+
+        // Check if this is a flat array of strings (scalar/root-level errors)
+        if (self::isFlatErrorArray($errors)) {
+            // This is a root-level error (scalar validator or container type error)
+            $path = $basePath === '' ? '_root' : $basePath;
+            foreach ($errors as $message) {
+                if (!is_string($message)) {
+                    continue;
+                }
+                $result[] = ['path' => $path, 'message' => $message];
+            }
+            return $result;
+        }
+
+        // This is a nested structure - recurse through it
+        foreach ($errors as $key => $value) {
+            $currentPath = self::buildPath($basePath, (string) $key);
+
+            if (!is_array($value)) {
+                if (is_string($value)) {
+                    // Single string error at this level
+                    $result[] = ['path' => $currentPath, 'message' => $value];
+                }
+                continue;
+            }
+
+            if (self::isFlatErrorArray($value)) {
+                // This is a field-level error array
+                foreach ($value as $message) {
+                    if (!is_string($message)) {
+                        continue;
+                    }
+                    $result[] = ['path' => $currentPath, 'message' => $message];
+                }
+                continue;
+            }
+
+            // This is a nested structure - recurse
+            $result = array_merge($result, self::flattenErrorsRecursive($value, $currentPath));
+        }
+
+        return $result;
+    }
+
+    /**
+     * Checks if an array is a flat array of strings (error messages).
+     *
+     * @param array<array-key, mixed> $array
+     * @return bool
+     */
+    private static function isFlatErrorArray(array $array): bool
+    {
+        // Empty array is considered flat
+        if ($array === []) {
+            return false;
+        }
+
+        // Check if all values are strings and keys are numeric (0-indexed)
+        foreach ($array as $key => $value) {
+            if (is_int($key) && is_string($value)) {
+                continue;
+            }
+            return false;
+        }
+
+        // Check if keys are sequential starting from 0
+        $keys = array_keys($array);
+        return $keys === range(0, count($array) - 1);
+    }
+
+    /**
+     * Builds a path string by concatenating base path with a key.
+     *
+     * @param string $basePath The base path
+     * @param string $key The key to append
+     * @return string The combined path
+     */
+    private static function buildPath(string $basePath, string $key): string
+    {
+        if ($basePath === '') {
+            return $key;
+        }
+
+        return $basePath . '.' . $key;
+    }
 }