docs: add cross-item validation with field-level error paths

lemmon · lemmon · commit b2679e6e77a4 · 2026-01-07T17:37:28.000+01:00
Document the nested error structure pattern for cross-item array validation (uniqueness, relationships) that enables field-level error paths like symlinks.2.destination. Added examples to array-validation, custom-validation, and error-handling guides. Updated planning docs with uniqueField() feature. Updated llms.txt for AI agent reference.
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -262,14 +262,15 @@ $stringValidator = Validator::isString()
 ### Array Enhancements
 - [x] **`minItems()`** / **`maxItems()`** - Array length constraints
 - [x] **`contains()`** - Validates array contains specific item or item matching validator
+- [ ] **`uniqueField(string $fieldName, ?string $message = null)`** - Validates uniqueness of a specific field across array items with field-level error paths (e.g., `symlinks.2.destination`); convenience wrapper around `satisfies()` for common use case
 
 ### Array Transformations
 - [x] **`transform()`** / **`pipe()`** - Generic transformation methods (already implemented!)
 - [x] **`nullifyEmpty()`** - Convert empty arrays to null (already implemented!)
 - [x] **`filterEmpty()`** - Remove empty/null values and reindex automatically (already implemented!)
 
 ### Removed from Scope
-- ~~`unique()`~~ -- Use `array_unique()` or Laravel Collections (complex deduplication logic)
+- ~~`unique()`~~ -- Use `array_unique()` or Laravel Collections (complex deduplication logic). Note: `uniqueField()` validates uniqueness of a specific field across array items, which is different from deduplicating the array itself.
 - ~~`flatten()`~~ -- Complex recursive logic, use Laravel Collections or `array_merge_recursive()`
 
 ### Numeric Enhancements
diff --git a/TASKS.md b/TASKS.md
@@ -22,3 +22,6 @@ Public repo; keep this list short (about 7) and up to date. Rules: no numbering
 
 - Property-based tests
   - Add a small property-based test set for key validators (string patterns, numeric constraints) to harden edge cases and catch regressions.
+
+- `uniqueField()` array validation method
+  - Add `uniqueField(string $fieldName, ?string $message = null)` to ArrayValidator for validating uniqueness of nested fields across array items; convenience wrapper around `satisfies()` that automatically handles nested error structure for field-level error paths (e.g., `symlinks.2.destination`); common use case that deserves convenience method similar to Laravel's `distinct` rule.
diff --git a/docs/guides/array-validation.md b/docs/guides/array-validation.md
@@ -458,6 +458,104 @@ try {
 }
 ```
 
+## Cross-Item Validation
+
+For validations that need to check relationships across multiple array items (like uniqueness), use `satisfies()` on the array validator. To attach errors to specific fields within items, use a nested error structure.
+
+### Uniqueness Validation with Field-Level Errors
+
+When validating uniqueness of a nested field (e.g., `destination` in each symlink), structure errors to attach them to the specific field:
+
+```php
+$schema = Validator::isAssociative([
+    'symlinks' => Validator::isArray()
+        ->items(Validator::isAssociative([
+            'source' => Validator::isString()->default('.'),
+            'destination' => Validator::isString()->required(),
+        ]))
+        ->satisfies(
+            function ($symlinks, $key, $input) {
+                // Extract all destination values with their indices
+                $destinations = [];
+                foreach ($symlinks as $index => $symlink) {
+                    if (isset($symlink['destination'])) {
+                        $dest = $symlink['destination'];
+                        if (!isset($destinations[$dest])) {
+                            $destinations[$dest] = [];
+                        }
+                        $destinations[$dest][] = $index;
+                    }
+                }
+
+                // Check for duplicates
+                $duplicates = [];
+                foreach ($destinations as $dest => $indices) {
+                    if (count($indices) > 1) {
+                        $duplicates[$dest] = $indices;
+                    }
+                }
+
+                if (empty($duplicates)) {
+                    return true;
+                }
+
+                // Nested error structure: [index => [field => [message]]]
+                // This creates field-level error paths: 'symlinks.2.destination'
+                $errors = [];
+                foreach ($duplicates as $dest => $indices) {
+                    // Mark all but the first occurrence as duplicates
+                    foreach (array_slice($indices, 1) as $idx) {
+                        $errors[$idx] = [
+                            'destination' => [
+                                "Destination '{$dest}' is not unique (also used at index {$indices[0]})"
+                            ]
+                        ];
+                    }
+                }
+
+                throw new ValidationException($errors);
+            },
+            'All destinations must be unique'
+        )
+        ->required(),
+]);
+
+$input = [
+    'symlinks' => [
+        ['source' => 'path1', 'destination' => '/same/path'],
+        ['source' => 'path2', 'destination' => '/unique/path'],
+        ['source' => 'path3', 'destination' => '/same/path'], // Duplicate
+    ],
+];
+
+try {
+    $schema->validate($input);
+} catch (ValidationException $e) {
+    $flattened = $e->getFlattenedErrors();
+    // [
+    //     ['path' => 'symlinks.2.destination', 'message' => "Destination '/same/path' is not unique (also used at index 0)"]
+    // ]
+}
+```
+
+**Key Pattern:** Structure errors as `[arrayIndex => [fieldName => [errorMessage]]]` to get field-level error paths. The flattening logic automatically builds paths like `symlinks.2.destination` from this nested structure.
+
+### Simple Uniqueness Check (Array-Level Error)
+
+If you don't need field-level errors, you can use a simpler approach that returns a single error at the array level:
+
+```php
+->satisfies(
+    function ($items) {
+        $destinations = array_column($items, 'destination');
+        return count($destinations) === count(array_unique($destinations));
+    },
+    'All destination values must be unique'
+)
+```
+
+This will produce an error at `symlinks` rather than `symlinks.2.destination`.
+
 ## Advanced Examples
 
 ### File Upload Validation
diff --git a/docs/guides/custom-validation.md b/docs/guides/custom-validation.md
@@ -288,6 +288,107 @@ $validator = Validator::isString()
 - Validators that frequently receive specification updates or new variants
 - Production applications requiring comprehensive validation features
 
+## Cross-Item Array Validation
+
+For validations that need to check relationships across multiple array items (like uniqueness, ordering, or dependencies), use `satisfies()` on the array validator. This runs **after** item validation, so you receive the validated data structure.
+
+### Uniqueness Validation with Field-Level Errors
+
+When validating uniqueness of a nested field across array items, structure errors to attach them to specific fields within items:
+
+```php
+$schema = Validator::isAssociative([
+    'items' => Validator::isArray()
+        ->items(Validator::isAssociative([
+            'id' => Validator::isInt()->required(),
+            'name' => Validator::isString()->required(),
+        ]))
+        ->satisfies(
+            function ($items, $key, $input) {
+                // Check uniqueness of 'id' field
+                $ids = [];
+                foreach ($items as $index => $item) {
+                    if (isset($item['id'])) {
+                        $id = $item['id'];
+                        $ids[$id][] = $index;
+                    }
+                }
+
+                $duplicates = [];
+                foreach ($ids as $id => $indices) {
+                    if (count($indices) > 1) {
+                        $duplicates[$id] = $indices;
+                    }
+                }
+
+                if (empty($duplicates)) {
+                    return true;
+                }
+
+                // Nested error structure: [index => [field => [message]]]
+                // This creates field-level error paths: 'items.2.id'
+                $errors = [];
+                foreach ($duplicates as $id => $indices) {
+                    foreach (array_slice($indices, 1) as $idx) {
+                        $errors[$idx] = [
+                            'id' => ["ID {$id} is not unique (also used at index {$indices[0]})"]
+                        ];
+                    }
+                }
+
+                throw new ValidationException($errors);
+            }
+        )
+]);
+
+$input = [
+    'items' => [
+        ['id' => 1, 'name' => 'First'],
+        ['id' => 2, 'name' => 'Second'],
+        ['id' => 1, 'name' => 'Duplicate'], // Duplicate ID
+    ],
+];
+
+try {
+    $schema->validate($input);
+} catch (ValidationException $e) {
+    $flattened = $e->getFlattenedErrors();
+    // [
+    //     ['path' => 'items.2.id', 'message' => 'ID 1 is not unique (also used at index 0)']
+    // ]
+}
+```
+
+**Key Pattern:** Structure errors as `[arrayIndex => [fieldName => [errorMessage]]]` to get field-level error paths. The error flattening logic automatically builds paths like `items.2.id` from this nested structure.
+
+### Other Cross-Item Validations
+
+This pattern works for any cross-item validation:
+
+```php
+// Validate that items are in ascending order by 'order' field
+->satisfies(
+    function ($items) {
+        $orders = array_column($items, 'order');
+        $sorted = $orders;
+        sort($sorted);
+        return $orders === $sorted;
+    },
+    'Items must be in ascending order'
+)
+
+// Validate that total doesn't exceed limit
+->satisfies(
+    function ($items, $key, $input) {
+        $total = array_sum(array_column($items, 'amount'));
+        return $total <= ($input['limit'] ?? 1000);
+    },
+    'Total amount exceeds limit'
+)
+```
+
+## External Library Integration
+
 ```php
 // UUID validation with ramsey/uuid (recommended for production)
 use Ramsey\Uuid\Uuid;
diff --git a/docs/guides/error-handling.md b/docs/guides/error-handling.md
@@ -202,6 +202,9 @@ $invalidData = [
 
 For arrays with item validators, errors preserve array indices to identify which item failed:
 
+**Standard Item Errors:**
+Errors from item validation automatically preserve indices:
+
 ```php
 $schema = Validator::isAssociative([
     'items' => Validator::isArray()->items(Validator::isInt()->min(1)),
@@ -253,10 +256,73 @@ try {
     // [
     //     ['path' => 'users.0.email', 'message' => 'Value is required'],
     //     ['path' => 'users.1.email', 'message' => 'Value must be a valid email address']
+    //     ]
+}
+```
+
+**Cross-Item Validation Errors (Field-Level):**
+
+For cross-item validations (like uniqueness) that need to attach errors to specific fields within items, use nested error structure:
+
+```php
+$schema = Validator::isAssociative([
+    'symlinks' => Validator::isArray()
+        ->items(Validator::isAssociative([
+            'destination' => Validator::isString()->required(),
+        ]))
+        ->satisfies(
+            function ($symlinks) {
+                // Check uniqueness
+                $destinations = [];
+                foreach ($symlinks as $index => $item) {
+                    $dest = $item['destination'] ?? null;
+                    if ($dest) {
+                        $destinations[$dest][] = $index;
+                    }
+                }
+
+                $duplicates = [];
+                foreach ($destinations as $dest => $indices) {
+                    if (count($indices) > 1) {
+                        $duplicates[$dest] = $indices;
+                    }
+                }
+
+                if (empty($duplicates)) return true;
+
+                // Nested structure: [index => [field => [message]]]
+                // Flattens to 'symlinks.2.destination'
+                $errors = [];
+                foreach ($duplicates as $dest => $indices) {
+                    foreach (array_slice($indices, 1) as $idx) {
+                        $errors[$idx] = [
+                            'destination' => ["'{$dest}' is not unique"]
+                        ];
+                    }
+                }
+                throw new ValidationException($errors);
+            }
+        )
+]);
+
+try {
+    $schema->validate([
+        'symlinks' => [
+            ['destination' => '/path1'],
+            ['destination' => '/path2'],
+            ['destination' => '/path1'], // Duplicate
+        ],
+    ]);
+} catch (ValidationException $e) {
+    $flattened = $e->getFlattenedErrors();
+    // [
+    //     ['path' => 'symlinks.2.destination', 'message' => "'/path1' is not unique"]
     // ]
 }
 ```
 
+**Key Pattern:** Structure errors as `[arrayIndex => [fieldName => [errorMessage]]]` to get field-level error paths in flattened output.
+
 ## Error Message Customization
 
 ### Built-in Validator Messages
diff --git a/llms.txt b/llms.txt
@@ -115,6 +115,8 @@ maxItems(int $max, ?string $message = null): static
 contains(mixed|FieldValidator $valueOrValidator, ?string $message = null): static
 ```
 
+**Cross-Item Validation:** Use `satisfies()` on array validator for uniqueness/relationships. Structure errors as `[index => [field => [message]]]` to get field-level paths (e.g., `symlinks.2.destination`). Runs after item validation, receives validated data structure.
+
 ### AssociativeValidator / ObjectValidator
 *Schema validation*
 ```php
