feat(FieldValidator): add outputKey() for schema output key remapping

- Add outputKey(string $key) to allow schema fields to output under a different key
- AssociativeValidator and ObjectValidator use output key when assigning validated values
- Update llms.txt, docs (object-validation, validator-factory), CHANGELOG, ROADMAP

Author: lemmon

CHANGELOG.md

@@ -5,6 +5,7 @@ All notable changes to this project will be documented in this file.
 ## [Unreleased]
 
 ### Added
+- `outputKey(string $key)` on `FieldValidator` for schema fields: output validated values under a different key than the input field (e.g. input `service_id` -> output `service` after transform); works with `Validator::isAssociative()` and `Validator::isObject()`
 - GitHub Actions CI: lint, platform-check, static analysis, tests on PHP 8.3
 
 ### Changed

ROADMAP.md

@@ -14,7 +14,7 @@ Focused on core validation primitives, consistent pipelines, and extensibility v
 ## Next Minor Release
 
 - [ ] Universal allowed-value validators: `enum()` (PHP BackedEnum) and `const()` (single allowed value)
-- [ ] Schema output key remapping: `outputKey(string $key)`
+- [x] Schema output key remapping: `outputKey(string $key)`
 - [ ] Structured error codes in validation errors (backward compatible)
 - [ ] ArrayValidator `uniqueField(string $fieldName, ?string $message = null)`
 - [ ] Mutation testing pilot (Infection + baseline)

docs/api-reference/validator-factory.md

@@ -663,6 +663,28 @@ $result = $validator->validate(''); // Returns: 'N/A'
 
 ---
 
+### `outputKey(string $key): self`
+
+**Schema fields only.** Emits the validated value under a different key than the input field. Only applies when the validator is used inside `Validator::isAssociative()` or `Validator::isObject()`.
+
+```php
+$schema = Validator::isAssociative([
+    'service_id' => Validator::isString()->uuid()->outputKey('service'),
+]);
+
+$result = $schema->validate(['service_id' => '550e8400-e29b-41d4-a716-446655440000']);
+// Result: ['service' => '550e8400-...'] (not 'service_id')
+```
+
+**Parameters:**
+- `$key`: The key to use in the output structure
+
+**Returns:** Same validator instance for method chaining.
+
+**See Also:** [Object & Schema Validation Guide](../guides/object-validation.md#output-key-remapping)
+
+---
+
 ### `in(array $values, ?string $message = null): self`
 
 **Available on:** `StringValidator`, `IntValidator`, `FloatValidator`, `BoolValidator` only

docs/guides/object-validation.md

@@ -7,6 +7,7 @@ This guide covers validation of structured data using `AssociativeValidator` (fo
 - [Associative Array Validation](#associative-array-validation)
 - [Object Validation](#object-validation)
 - [Schema Definition](#schema-definition)
+- [Output Key Remapping](#output-key-remapping)
 - [Type Coercion](#type-coercion)
 - [Advanced Features](#advanced-features)
 - [Common Patterns](#common-patterns)
@@ -121,6 +122,38 @@ $result = $schema->validate($input);
 // Result: ['name' => 'John', 'status' => 'active', 'priority' => 1]
 ```
 
+### Output Key Remapping
+
+Use `outputKey()` on schema fields to emit validated values under a different key than the input field. This is useful when the input uses snake_case or IDs while the output should use different property names (e.g. for API responses or after transforming IDs to entities).
+
+```php
+$schema = Validator::isAssociative([
+    'service_id' => Validator::isString()->uuid()->outputKey('service'),
+    'user_id' => Validator::isString()->uuid()->outputKey('user'),
+]);
+
+$input = [
+    'service_id' => '550e8400-e29b-41d4-a716-446655440000',
+    'user_id' => '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+];
+
+$result = $schema->validate($input);
+// Result: ['service' => '550e8400-...', 'user' => '6ba7b810-...']
+// Note: 'service_id' and 'user_id' are not in the result
+```
+
+Works with `transform()` for ID-to-entity resolution:
+
+```php
+$schema = Validator::isAssociative([
+    'service_id' => Validator::isString()->uuid()
+        ->transform(fn(string $id) => $serviceRepo->find($id))
+        ->outputKey('service'),
+]);
+```
+
+Works with both `Validator::isAssociative()` and `Validator::isObject()`.
+
 ### Field Inclusion Behavior
 
 Schema validators only include fields in the result that were either:

llms.txt

@@ -50,6 +50,7 @@ static not(FieldValidator $validator, ?string $message = null): FieldValidator
 required(?string $message = null): static
 default(mixed $value): static
 coerce(): static
+outputKey(string $key): static (schema fields only: output under different key, e.g. input service_id -> output service)
 nullifyEmpty(): static (transforms '' or [] to null)
 clone(): static (deep copy with bound closures)
 

src/Lemmon/Validator/AssociativeValidator.php

@@ -84,7 +84,8 @@ protected function validateType(mixed $value, string $key): mixed
             $hasDefault = $validator->hasDefault ?? false;
 
             if ($wasProvided || $hasDefault) {
-                $data[$fieldKey] = $validatedFieldValue;
+                $dataKey = $validator->outputKey ?? $fieldKey;
+                $data[$dataKey] = $validatedFieldValue;
             }
         }
 

src/Lemmon/Validator/FieldValidator.php

@@ -11,6 +11,7 @@ abstract class FieldValidator
     protected bool $coerce = false;
     protected bool $required = false;
     protected ?string $requiredMessage = null;
+    protected ?string $outputKey = null;
 
     /**
      * Creates a deep copy of the validator, including pipeline closures bound to the clone.
@@ -68,6 +69,19 @@ public function coerce(): self
         return $this;
     }
 
+    /**
+     * Sets the output key for schema fields. When used in AssociativeValidator or ObjectValidator,
+     * the validated value is stored under this key instead of the input field key.
+     *
+     * @param string $key The key to use in the output structure
+     * @return $this
+     */
+    public function outputKey(string $key): self
+    {
+        $this->outputKey = $key;
+        return $this;
+    }
+
     /**
      * Enables nullification of empty values (empty string, empty array) to null.
      *

src/Lemmon/Validator/ObjectValidator.php

@@ -84,7 +84,8 @@ protected function validateType(mixed $value, string $key): mixed
             $hasDefault = $validator->hasDefault ?? false;
 
             if ($wasProvided || $hasDefault) {
-                $data->{$fieldKey} = $validatedFieldValue;
+                $dataKey = $validator->outputKey ?? $fieldKey;
+                $data->{$dataKey} = $validatedFieldValue;
             }
         }
 

tests/AssociativeValidatorTest.php

@@ -235,3 +235,57 @@
     expect(fn() => $schema->validate('not-empty'))
         ->toThrow(ValidationException::class, 'Input must be an associative array');
 });
+
+it('should remap output key with outputKey when field is provided', function () {
+    $schema = Validator::isAssociative([
+        'service_id' => Validator::isString()->uuid()->outputKey('service'),
+        'user_id' => Validator::isString()->uuid()->outputKey('user'),
+    ]);
+
+    $input = [
+        'service_id' => '550e8400-e29b-41d4-a716-446655440000',
+        'user_id' => '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+    ];
+
+    $data = $schema->validate($input);
+
+    expect($data)->toBe([
+        'service' => '550e8400-e29b-41d4-a716-446655440000',
+        'user' => '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+    ]);
+    expect($data)->not->toHaveKey('service_id');
+    expect($data)->not->toHaveKey('user_id');
+});
+
+it('should remap output key with outputKey combined with transform', function () {
+    $schema = Validator::isAssociative([
+        'service_id' => Validator::isString()
+            ->uuid()
+            ->transform(fn(string $id) => ['id' => $id, 'type' => 'service'])
+            ->outputKey('service'),
+    ]);
+
+    $input = [
+        'service_id' => '550e8400-e29b-41d4-a716-446655440000',
+    ];
+
+    $data = $schema->validate($input);
+
+    expect($data)->toBe([
+        'service' => ['id' => '550e8400-e29b-41d4-a716-446655440000', 'type' => 'service'],
+    ]);
+});
+
+it('should remap output key for fields with default values', function () {
+    $schema = Validator::isAssociative([
+        'level' => Validator::isInt()
+            ->coerce()
+            ->default(3)
+            ->outputKey('tier'),
+    ])->coerceAll();
+
+    $data = $schema->validate([]);
+
+    expect($data)->toBe(['tier' => 3]);
+    expect($data)->not->toHaveKey('level');
+});

tests/ObjectValidatorTest.php

@@ -203,3 +203,22 @@
     expect(fn() => $schema->validate('not-empty'))
         ->toThrow(ValidationException::class, 'Input must be an object');
 });
+
+it('should remap output key with outputKey when field is provided', function () {
+    $schema = Validator::isObject([
+        'service_id' => Validator::isString()->uuid()->outputKey('service'),
+        'user_id' => Validator::isString()->uuid()->outputKey('user'),
+    ]);
+
+    $input = (object) [
+        'service_id' => '550e8400-e29b-41d4-a716-446655440000',
+        'user_id' => '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+    ];
+
+    $data = $schema->validate($input);
+
+    expect($data)->toHaveProperty('service', '550e8400-e29b-41d4-a716-446655440000');
+    expect($data)->toHaveProperty('user', '6ba7b810-9dad-11d1-80b4-00c04fd430c8');
+    expect($data)->not->toHaveProperty('service_id');
+    expect($data)->not->toHaveProperty('user_id');
+});