From 9355da09126e119a34fccd3a55c2aa1a2c35ea7c Mon Sep 17 00:00:00 2001
From: bigdevlarry <suleabimbola@gmail.com>
Date: Thu, 19 Mar 2026 22:48:32 +0000
Subject: [PATCH] Fix to let schema attribute enum type hint allow null values

---
 src/Capability/Attribute/Schema.php           | 46 +++++++++----------
 src/Capability/Discovery/SchemaGenerator.php  |  2 +-
 .../Discovery/SchemaValidatorTest.php         |  3 ++
 3 files changed, 27 insertions(+), 24 deletions(-)

diff --git a/src/Capability/Attribute/Schema.php b/src/Capability/Attribute/Schema.php
index 5e5507f0..80ec4b53 100644
--- a/src/Capability/Attribute/Schema.php
+++ b/src/Capability/Attribute/Schema.php
@@ -24,8 +24,8 @@
  *     definition?: array<string, mixed>,
  *     type?: string,
  *     description?: string,
- *     enum?: array<int, float|string|int>,
- *     gormat?: string,
+ *     enum?: array<int, int|float|string|null>,
+ *     format?: string,
  *     minLength?: int,
  *     maxLength?: int,
  *     pattern?: string,
@@ -64,7 +64,7 @@ class Schema
     public ?string $description = null;
     public mixed $default = null;
     /**
-     * @var ?array<int, float|string|int>
+     * @var ?array<int, int|float|string|null>
      */
     public ?array $enum = null; // list of allowed values
     public ?string $format = null; // e.g., 'email', 'date-time'
@@ -105,26 +105,26 @@ class Schema
     public bool|array|null $additionalProperties = null; // true, false, or a schema array
 
     /**
-     * @param ?array<string, mixed>          $definition           A complete JSON schema array. If provided, other parameters are ignored.
-     * @param ?string                        $type                 the JSON schema type
-     * @param ?string                        $description          description of the element
-     * @param ?array<int, float|string|int>  $enum                 allowed enum values
-     * @param ?string                        $format               String format (e.g., 'date-time', 'email').
-     * @param ?int                           $minLength            minimum length for strings
-     * @param ?int                           $maxLength            maximum length for strings
-     * @param ?string                        $pattern              regex pattern for strings
-     * @param int|float|null                 $minimum              minimum value for numbers/integers
-     * @param int|float|null                 $maximum              maximum value for numbers/integers
-     * @param ?bool                          $exclusiveMinimum     exclusive minimum
-     * @param ?bool                          $exclusiveMaximum     exclusive maximum
-     * @param int|float|null                 $multipleOf           must be a multiple of this value
-     * @param ?array<string, mixed>          $items                JSON Schema for items if type is 'array'
-     * @param ?int                           $minItems             minimum items for an array
-     * @param ?int                           $maxItems             maximum items for an array
-     * @param ?bool                          $uniqueItems          whether array items must be unique
-     * @param ?array<string, mixed>          $properties           Property definitions if type is 'object'. [name => schema_array].
-     * @param ?array<int, string>            $required             list of required properties for an object
-     * @param bool|array<string, mixed>|null $additionalProperties policy for additional properties in an object
+     * @param ?array<string, mixed>              $definition           A complete JSON schema array. If provided, other parameters are ignored.
+     * @param ?string                            $type                 the JSON schema type
+     * @param ?string                            $description          description of the element
+     * @param ?array<int, int|float|string|null> $enum                 allowed enum values
+     * @param ?string                            $format               String format (e.g., 'date-time', 'email').
+     * @param ?int                               $minLength            minimum length for strings
+     * @param ?int                               $maxLength            maximum length for strings
+     * @param ?string                            $pattern              regex pattern for strings
+     * @param int|float|null                     $minimum              minimum value for numbers/integers
+     * @param int|float|null                     $maximum              maximum value for numbers/integers
+     * @param ?bool                              $exclusiveMinimum     exclusive minimum
+     * @param ?bool                              $exclusiveMaximum     exclusive maximum
+     * @param int|float|null                     $multipleOf           must be a multiple of this value
+     * @param ?array<string, mixed>              $items                JSON Schema for items if type is 'array'
+     * @param ?int                               $minItems             minimum items for an array
+     * @param ?int                               $maxItems             maximum items for an array
+     * @param ?bool                              $uniqueItems          whether array items must be unique
+     * @param ?array<string, mixed>              $properties           Property definitions if type is 'object'. [name => schema_array].
+     * @param ?array<int, string>                $required             list of required properties for an object
+     * @param bool|array<string, mixed>|null     $additionalProperties policy for additional properties in an object
      */
     public function __construct(
         ?array $definition = null,
diff --git a/src/Capability/Discovery/SchemaGenerator.php b/src/Capability/Discovery/SchemaGenerator.php
index dab9cbb5..6366fd49 100644
--- a/src/Capability/Discovery/SchemaGenerator.php
+++ b/src/Capability/Discovery/SchemaGenerator.php
@@ -46,7 +46,7 @@
  *     type?: string|array,
  *     description?: string,
  *     default?: mixed,
- *     enum?: array<string|int>,
+ *     enum?: array<int, int|float|string|null>,
  *     items?: array<string, mixed>,
  * }
  * @phpstan-type VariadicParameterSchema array{
diff --git a/tests/Unit/Capability/Discovery/SchemaValidatorTest.php b/tests/Unit/Capability/Discovery/SchemaValidatorTest.php
index 417ddbde..7e8a2072 100644
--- a/tests/Unit/Capability/Discovery/SchemaValidatorTest.php
+++ b/tests/Unit/Capability/Discovery/SchemaValidatorTest.php
@@ -471,6 +471,7 @@ private function getSimpleSchema(): array
                 'active' => ['type' => 'boolean'],
                 'score' => ['type' => 'number'],
                 'items' => ['type' => 'array', 'items' => ['type' => 'string']],
+                'status' => ['enum' => [null, 'active', 'inactive']],
                 'nullableValue' => ['type' => ['string', 'null']],
                 'optionalValue' => ['type' => 'string'],
             ],
@@ -486,6 +487,7 @@ private function getSimpleSchema(): array
      *     active: bool,
      *     score: float,
      *     items: string[],
+     *     status: 'active'|'inactive'|null,
      *     nullableValue: null,
      *     optionalValue: string
      * }
@@ -498,6 +500,7 @@ private function getValidData(): array
             'active' => true,
             'score' => 99.5,
             'items' => ['a', 'b'],
+            'status' => null,
             'nullableValue' => null,
             'optionalValue' => 'present',
         ];