feat: Allow additional properties to accept schema (#4)

Author: tymondesigns

README.md

@@ -431,13 +431,43 @@ $schema = SchemaFactory::object('config')
     // Control number of properties
     ->minProperties(1)
     ->maxProperties(10)
-    ->additionalProperties(false);
+    // Control additional properties
+    ->additionalProperties(false); // Disallow additional properties
+
+// Or validate additional properties against a schema
+$schema = SchemaFactory::object('config')
+    ->properties(
+        SchemaFactory::string('name')->required(),
+        SchemaFactory::string('type')->required(),
+    )
+    ->additionalProperties(
+        SchemaFactory::string()->minLength(3)
+    );
 ```
 
 ```php
 // Property names must be alphabetic
 $schema->isValid(['123' => 'value']); // false
 $schema->isValid(['validKey' => 'value']); // true
+
+// Additional properties must match schema
+$schema->isValid([
+    'name' => 'config1',
+    'type' => 'test',
+    'extra' => 'valid', // valid: string with length >= 3
+]); // true
+
+$schema->isValid([
+    'name' => 'config1',
+    'type' => 'test',
+    'extra' => 'no', // invalid: string too short
+]); // false
+
+$schema->isValid([
+    'name' => 'config1',
+    'type' => 'test',
+    'extra' => 123, // invalid: wrong type
+]); // false
 ```
 
 Objects also support pattern-based property validation using `patternProperties`:
@@ -918,6 +948,43 @@ $schema->toJson();
 }
 ```
 
+### From an Backed Enum
+
+```php
+use Cortex\JsonSchema\SchemaFactory;
+
+/**
+ * This is the description of the enum
+ */
+enum PostType: int
+{
+    case Article = 1;
+    case News = 2;
+    case Tutorial = 3;
+}
+
+// Build the schema from the enum
+$schema = SchemaFactory::fromEnum(PostType::class);
+
+// Convert to JSON Schema
+$schema->toJson();
+```
+
+```json
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "description": "This is the description of the enum",
+    "properties": {
+        "PostType": {
+            "type": "integer",
+            "enum": [1, 2, 3]
+        }
+    },
+    "required": ["PostType"]
+}
+```
+
 ## Credits
 
 - [Sean Tymon](https://github.com/tymondesigns)

src/Types/Concerns/HasProperties.php

@@ -20,7 +20,10 @@ trait HasProperties
      */
     protected array $requiredProperties = [];
 
-    protected ?bool $additionalProperties = null;
+    /**
+     * @var bool|\Cortex\JsonSchema\Contracts\Schema|null
+     */
+    protected mixed $additionalProperties = null;
 
     protected ?int $minProperties = null;
 
@@ -58,9 +61,11 @@ public function properties(Schema ...$properties): static
     }
 
     /**
-     * Allow or disallow additional properties
+     * Set whether additional properties are allowed and optionally their schema
+     *
+     * @param bool|\Cortex\JsonSchema\Contracts\Schema $allowed Whether additional properties are allowed, or a schema they must match
      */
-    public function additionalProperties(bool $allowed): static
+    public function additionalProperties(bool|Schema $allowed): static
     {
         $this->additionalProperties = $allowed;
 
@@ -188,7 +193,9 @@ protected function addPropertiesToSchema(array $schema): array
         }
 
         if ($this->additionalProperties !== null) {
-            $schema['additionalProperties'] = $this->additionalProperties;
+            $schema['additionalProperties'] = $this->additionalProperties instanceof Schema
+                ? $this->additionalProperties->toArray(includeSchemaRef: false, includeTitle: false)
+                : $this->additionalProperties;
         }
 
         if ($this->propertyNames !== null) {

tests/Unit/Targets/ObjectSchemaTest.php

@@ -136,6 +136,48 @@
     ]))->not->toThrow(SchemaException::class);
 });
 
+it('can create an object schema with additional properties schema', function (): void {
+    $schema = Schema::object('config')
+        ->description('Configuration object')
+        ->properties(
+            Schema::string('name')->required(),
+            Schema::string('type')->required(),
+        )
+        ->additionalProperties(Schema::string()->minLength(3));
+
+    $schemaArray = $schema->toArray();
+
+    expect($schemaArray['additionalProperties'])->toHaveKey('type', 'string');
+    expect($schemaArray['additionalProperties'])->toHaveKey('minLength', 3);
+
+    // Validation tests - valid additional property
+    expect(fn() => $schema->validate([
+        'name' => 'config1',
+        'type' => 'test',
+        'extra' => 'valid', // additional property matching schema
+    ]))->not->toThrow(SchemaException::class);
+
+    // Validation tests - invalid additional property (too short)
+    expect(fn() => $schema->validate([
+        'name' => 'config1',
+        'type' => 'test',
+        'extra' => 'no', // additional property not matching schema
+    ]))->toThrow(
+        SchemaException::class,
+        'All additional object properties must match schema: extra',
+    );
+
+    // Validation tests - invalid additional property (wrong type)
+    expect(fn() => $schema->validate([
+        'name' => 'config1',
+        'type' => 'test',
+        'extra' => 123, // additional property not matching schema
+    ]))->toThrow(
+        SchemaException::class,
+        'All additional object properties must match schema: extra',
+    );
+});
+
 it('can create an object schema with property count constraints', function (): void {
     $schema = Schema::object('metadata')
         ->description('Metadata object')