feat(schema): add passthrough for undeclared keys

- Extract SchemaValidatorOptionsTrait for coerceAll, passthrough, and schema clone helper
- Copy undeclared input keys/properties onto output after validation without overwriting outputKey targets
- Add tests and document behavior

Author: lemmon

AGENTS.md

@@ -19,7 +19,7 @@ Core validation logic lives in `src/Lemmon/Validator/`. Tests in `tests/` follow
 - **Validators:** `isString`, `isInt`, `isFloat`, `isBool`, `isArray`, `isAssociative`, `isObject`
 - **Shared:** `NumericConstraintsTrait` (min, max, multipleOf, etc.); `PipelineType` enum; variant enums `IpVersion`, `Base64Variant`, `UuidVariant` for format methods
 - **String formats:** email, URL, UUID, IP, hostname, domain, time, base64, hex, regex, datetime, date
-- **Schema validation:** AssociativeValidator/ObjectValidator with nested error aggregation
+- **Schema validation:** AssociativeValidator/ObjectValidator with nested error aggregation; shared `SchemaValidatorOptionsTrait` (`coerceAll`, `passthrough`, schema clone helper); `passthrough()` keeps undeclared keys/properties (unvalidated); default output is schema keys only
 - **Logical combinators:** `Validator::allOf`, `anyOf`, `not`; instance `satisfiesAny`, `satisfiesAll`, `satisfiesNone`; `const()` for single allowed value; `enum()` for BackedEnum
 - **Behavior:** Optional by default (null allowed unless `required()`); form-safe coercion (empty string → null, not 0/false); pipeline order guaranteed; fail-fast per field; `satisfies()` accepts validators or callables with `(value, key, input)`; extend via `satisfies()`, not custom validators
 

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- `passthrough()` on `AssociativeValidator` and `ObjectValidator`: copy undeclared keys or public properties from the input to the validated output without validating them; declared schema fields are still validated; values already written from the schema (including `outputKey` targets) are not overwritten by passthrough
+
 ## [0.14.0] - 2026-03-23
 
 ### Added

ROADMAP.md

@@ -24,7 +24,8 @@ Focused on core validation primitives, consistent pipelines, and extensibility v
 ## Future (Schema and Structure)
 
 - [ ] Schema composition: `partial()`, `pick()`, `omit()`, `merge()`
-- [ ] Unknown key policies: `strict()` (reject undeclared keys) and `passthrough()` (preserve undeclared keys)
+- [x] `passthrough()` on `AssociativeValidator` / `ObjectValidator` (preserve undeclared keys)
+- [ ] `strict()` (reject undeclared keys)
 - [ ] Explicit key deny-listing: `forbidKeys(array $keys, ?string $message = null)`
 - [ ] Key validation: `patternProperties()`, `propertyNames()`
 - [ ] Cross-field dependencies: `dependencies()`

docs/api-reference/validator-factory.md

@@ -135,7 +135,7 @@ $user = $userValidator->validate([
 
 **Returns:** `AssociativeValidator` instance with schema validation capabilities.
 
-**See Also:** [Object & Schema Validation Guide](../guides/object-validation.md)
+**See also:** [Object & Schema Validation Guide](../guides/object-validation.md) (`coerceAll()`, `passthrough()`, and schema patterns).
 
 ---
 
@@ -170,7 +170,7 @@ $validConfig = $configValidator->validate($config);
 
 **Returns:** `ObjectValidator` instance with schema validation capabilities.
 
-**See Also:** [Object & Schema Validation Guide](../guides/object-validation.md)
+**See also:** [Object & Schema Validation Guide](../guides/object-validation.md) (`coerceAll()`, `passthrough()`, and schema patterns).
 
 ---
 

docs/getting-started/core-concepts.md

@@ -115,6 +115,7 @@ Validator::isArray()->items($itemValidator) // With item validation
 ```php
 Validator::isAssociative($schema)       // Associative array with schema
 Validator::isObject($schema)            // stdClass object with schema
+// Optional on both: ->coerceAll(), ->passthrough() (keep undeclared keys unvalidated)
 ```
 
 ## Validation Flow

docs/guides/object-validation.md

@@ -8,6 +8,7 @@ This guide covers validation of structured data using `AssociativeValidator` (fo
 - [Object Validation](#object-validation)
 - [Schema Definition](#schema-definition)
 - [Output Key Remapping](#output-key-remapping)
+- [Passthrough (undeclared keys)](#passthrough-undeclared-keys)
 - [Type Coercion](#type-coercion)
 - [Advanced Features](#advanced-features)
 - [Common Patterns](#common-patterns)
@@ -156,7 +157,7 @@ Works with both `Validator::isAssociative()` and `Validator::isObject()`.
 
 ### Field Inclusion Behavior
 
-Schema validators only include fields in the result that were either:
+**By default**, schema validators only include fields in the result that were either:
 
 1. **Provided in the input data**, or
 2. **Have default values applied**
@@ -190,10 +191,41 @@ $result = $schema->validate($input);
 
 This behavior ensures that:
 
-- **Results accurately reflect the validated data** without unexpected properties
+- **Results accurately reflect the validated data** without unexpected properties (unless you opt into `passthrough()` below)
 - **Default values are consistently applied** when fields are missing
 - **Required field validation still works** (missing required fields cause validation to fail)
 
+### Passthrough (undeclared keys)
+
+Call `passthrough()` on a schema-backed `Validator::isAssociative()` or `Validator::isObject()` to **copy input keys that are not declared in the schema** onto the validated output **without validating them**. Declared fields are still run through their validators. Values already written from the schema (including keys produced by `outputKey()`) are **not** overwritten by passthrough.
+
+Passthrough runs only after all schema fields validate successfully. Copied values are shallow: nested arrays or objects are not recursively validated.
+
+```php
+$schema = Validator::isAssociative([
+    'name' => Validator::isString()->required(),
+])->passthrough();
+
+$input = [
+    'name' => 'Ann',
+    'metadata' => ['any' => 'structure'],
+    'version' => 1,
+];
+
+$result = $schema->validate($input);
+// Result includes name (validated) plus metadata and version (copied as-is)
+```
+
+With an **empty schema**, `passthrough()` keeps the entire map (still subject to array/object type rules and coercion on the container itself). That pattern is useful for optional opaque payloads such as API metadata:
+
+```php
+$result = Validator::isAssociative([])->passthrough()
+    ->validate(['foo' => 1, 'nested' => ['x' => true]]);
+// $result is the same associative shape, unvalidated
+```
+
+For `ObjectValidator`, only **public** properties on the input object are considered for passthrough (same visibility as `get_object_vars()`).
+
 ### Nested Schemas
 
 ```php

llms.txt

@@ -148,8 +148,11 @@ _Schema validation_
 ```php
 // Constructor accepts array<string, FieldValidator>
 coerceAll(): static // Recursively enables coercion on schema fields
+passthrough(): static // Copy undeclared keys/properties from input to output without validating them; schema fields still validated; does not overwrite keys already set from the schema (including outputKey targets)
 ```
 
+By default, outputs only schema-defined keys (plus defaults). With `passthrough()`, any input key not in the schema is copied through unchanged (shallow); nested structures are not recursively validated. For `ObjectValidator`, only **public** properties from the input object are considered (via `get_object_vars()`).
+
 ### BoolValidator
 
 ```php

src/Lemmon/Validator/AssociativeValidator.php

@@ -6,7 +6,7 @@
 
 class AssociativeValidator extends FieldValidator
 {
-    private bool $coerceAll = false;
+    use SchemaValidatorOptionsTrait;
 
     /**
      * @param array<string, FieldValidator> $schema
@@ -23,12 +23,6 @@ protected function getValidatorType(): string
         return 'associative_array';
     }
 
-    public function coerceAll(): self
-    {
-        $this->coerceAll = true;
-        return $this;
-    }
-
     /**
      * @inheritDoc
      */
@@ -93,15 +87,21 @@ protected function validateType(mixed $value, string $key): mixed
             throw new ValidationException($errors);
         }
 
+        if ($this->passthrough) {
+            foreach ($value as $inputKey => $rawValue) {
+                if (\array_key_exists($inputKey, $this->schema) || \array_key_exists($inputKey, $data)) {
+                    continue;
+                }
+                $data[$inputKey] = $rawValue;
+            }
+        }
+
         return $data;
     }
 
     public function __clone()
     {
         parent::__clone();
-
-        foreach ($this->schema as $fieldKey => $validator) {
-            $this->schema[$fieldKey] = $validator->clone();
-        }
+        $this->cloneSchemaFieldValidators();
     }
 }

src/Lemmon/Validator/ObjectValidator.php

@@ -6,7 +6,7 @@
 
 class ObjectValidator extends FieldValidator
 {
-    private bool $coerceAll = false;
+    use SchemaValidatorOptionsTrait;
 
     /**
      * @param array<string, FieldValidator> $schema
@@ -23,12 +23,6 @@ protected function getValidatorType(): string
         return 'object';
     }
 
-    public function coerceAll(): self
-    {
-        $this->coerceAll = true;
-        return $this;
-    }
-
     /**
      * @inheritDoc
      */
@@ -93,15 +87,21 @@ protected function validateType(mixed $value, string $key): mixed
             throw new ValidationException($errors);
         }
 
+        if ($this->passthrough) {
+            foreach (\get_object_vars($value) as $inputKey => $rawValue) {
+                if (\array_key_exists($inputKey, $this->schema) || \property_exists($data, $inputKey)) {
+                    continue;
+                }
+                $data->{$inputKey} = $rawValue;
+            }
+        }
+
         return $data;
     }
 
     public function __clone()
     {
         parent::__clone();
-
-        foreach ($this->schema as $fieldKey => $validator) {
-            $this->schema[$fieldKey] = $validator->clone();
-        }
+        $this->cloneSchemaFieldValidators();
     }
 }

src/Lemmon/Validator/SchemaValidatorOptionsTrait.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lemmon\Validator;
+
+/**
+ * Shared options and helpers for {@see AssociativeValidator} and {@see ObjectValidator}.
+ *
+ * Expects the using class to define a private `array<string, FieldValidator> $schema`.
+ */
+trait SchemaValidatorOptionsTrait
+{
+    private bool $coerceAll = false;
+
+    private bool $passthrough = false;
+
+    public function coerceAll(): self
+    {
+        $this->coerceAll = true;
+        return $this;
+    }
+
+    /**
+     * Preserve input members that are not declared in the schema, without validating them.
+     *
+     * Schema fields are still validated. Output members already set from the schema (including
+     * via {@see FieldValidator::outputKey()}) are not overwritten by passthrough values.
+     */
+    public function passthrough(): self
+    {
+        $this->passthrough = true;
+        return $this;
+    }
+
+    /**
+     * Deep-clone validators in the schema; call from {@see __clone()} after `parent::__clone()`.
+     */
+    protected function cloneSchemaFieldValidators(): void
+    {
+        foreach ($this->schema as $fieldKey => $validator) {
+            $this->schema[$fieldKey] = $validator->clone();
+        }
+    }
+}