Add class-level Definition and AdditionalProperty attributes

- Add Definition attribute for class-level schema metadata
- Add AdditionalProperty attribute for custom schema properties
- Update Schema class to support metadata and additional properties
- Update Generator to process both new attributes
- Add comprehensive unit tests
- Add usage examples

Author: butschster

.gitignore

@@ -10,4 +10,6 @@ docs
 vendor
 node_modules
 .php-cs-fixer.cache
-runtime
+runtime
+.context
+mcp-*.log

context.yaml

@@ -0,0 +1,28 @@
+$schema: 'https://raw.githubusercontent.com/context-hub/generator/refs/heads/main/json-schema.json'
+
+documents:
+  - description: 'Project structure overview'
+    outputPath: project-structure.md
+    overwrite: true
+    sources:
+      - type: tree
+        sourcePaths:
+          - src
+        filePattern: '*'
+        renderFormat: ascii
+        enabled: true
+        showCharCount: true
+
+  - description: 'Code base'
+    outputPath: code-base.md
+    sources:
+      - type: file
+        sourcePaths:
+          - src
+
+  - description: Unit tests
+    outputPath: unit-tests.md
+    sources:
+      - type: file
+        sourcePaths:
+          - tests

examples/DefinitionExample.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Examples;
+
+use Spiral\JsonSchemaGenerator\Attribute\AdditionalProperty;
+use Spiral\JsonSchemaGenerator\Attribute\Definition;
+use Spiral\JsonSchemaGenerator\Attribute\Field;
+use Spiral\JsonSchemaGenerator\Generator;
+
+#[Definition(
+    title: 'Product Schema',
+    description: 'A schema representing a product in an e-commerce system',
+    id: 'https://example.com/schemas/product.json',
+    schemaVersion: 'http://json-schema.org/draft-07/schema#',
+)]
+#[AdditionalProperty(name: 'additionalProperties', value: false)]
+#[AdditionalProperty(name: 'examples', value: [
+    [
+        'id' => 123,
+        'name' => 'Sample Product',
+        'price' => 99.99,
+        'tags' => ['new', 'featured'],
+        'status' => 'Active',
+    ],
+])]
+#[AdditionalProperty(name: 'maxProperties', value: 5)]
+class Product
+{
+    public function __construct(
+        #[Field(title: 'Product ID', description: 'Unique identifier for the product')]
+        public readonly int $id,
+        #[Field(title: 'Product Name', description: 'Name of the product')]
+        public readonly string $name,
+        #[Field(title: 'Product Price', description: 'Current price of the product')]
+        public readonly float $price,
+
+        /**
+         * @var array<string>
+         */
+        #[Field(title: 'Product Tags', description: 'List of tags associated with the product')]
+        public readonly array $tags = [],
+        #[Field(title: 'Product Status', description: 'Current status of the product')]
+        public readonly ?ProductStatus $status = null,
+    ) {}
+}
+
+#[Definition(title: 'Product Status')]
+#[AdditionalProperty(name: 'deprecated', value: ['Discontinued'])]
+enum ProductStatus: string
+{
+    case Active = 'Active';
+    case Inactive = 'Inactive';
+    case Discontinued = 'Discontinued';
+    case OutOfStock = 'Out of Stock';
+}
+
+// Generate the schema
+$generator = new Generator();
+$schema = $generator->generate(Product::class);
+
+// Output the schema as JSON
+\header('Content-Type: application/json');
+echo \json_encode($schema, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

src/Attribute/AdditionalProperty.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\JsonSchemaGenerator\Attribute;
+
+#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
+class AdditionalProperty
+{
+    public function __construct(
+        public readonly string $name,
+        public readonly mixed $value,
+    ) {}
+}

src/Attribute/Definition.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Spiral\JsonSchemaGenerator\Attribute;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+class Definition
+{
+    public function __construct(
+        public readonly ?string $title = null,
+        public readonly string $description = '',
+        public readonly ?string $id = null,
+        public readonly ?string $schemaVersion = null,
+    ) {}
+}

src/Attribute/Field.php

@@ -11,6 +11,5 @@ public function __construct(
         public readonly string $title = '',
         public readonly string $description = '',
         public readonly mixed $default = null,
-    ) {
-    }
+    ) {}
 }

src/Generator.php

@@ -4,6 +4,8 @@
 
 namespace Spiral\JsonSchemaGenerator;
 
+use Spiral\JsonSchemaGenerator\Attribute\AdditionalProperty;
+use Spiral\JsonSchemaGenerator\Attribute\Definition as ClassDefinition;
 use Spiral\JsonSchemaGenerator\Attribute\Field;
 use Spiral\JsonSchemaGenerator\Parser\ClassParserInterface;
 use Spiral\JsonSchemaGenerator\Parser\Parser;
@@ -35,6 +37,35 @@ public function generate(string|\ReflectionClass $class): Schema
 
         $schema = new Schema();
 
+        // Process class-level Definition attribute if present
+        $classDefinition = $class->findAttribute(ClassDefinition::class);
+        if ($classDefinition !== null) {
+            if (!empty($classDefinition->title)) {
+                $schema->setTitle($classDefinition->title);
+            } else {
+                // Use class short name as default title
+                $schema->setTitle($class->getShortName());
+            }
+
+            if (!empty($classDefinition->description)) {
+                $schema->setDescription($classDefinition->description);
+            }
+
+            if ($classDefinition->id !== null) {
+                $schema->setId($classDefinition->id);
+            }
+
+            if ($classDefinition->schemaVersion !== null) {
+                $schema->setSchemaVersion($classDefinition->schemaVersion);
+            }
+        } else {
+            // Set title to class name by default if no definition attribute
+            $schema->setTitle($class->getShortName());
+        }
+
+        // Process additional properties attributes if present
+        $this->processAdditionalProperties($class, $schema);
+
         $dependencies = [];
         // Generating properties
         foreach ($class->getProperties() as $property) {
@@ -80,14 +111,50 @@ public function generate(string|\ReflectionClass $class): Schema
         return $schema;
     }
 
+    /**
+     * Process AdditionalProperty attributes on a class
+     */
+    protected function processAdditionalProperties(ClassParserInterface $class, Schema $schema): void
+    {
+        // Get reflection class to extract attributes with \ReflectionClass::getAttributes()
+        try {
+            $reflectionClass = new \ReflectionClass($class->getName());
+            $additionalProperties = $reflectionClass->getAttributes(AdditionalProperty::class);
+
+            foreach ($additionalProperties as $additionalProperty) {
+                $instance = $additionalProperty->newInstance();
+                $schema->addAdditionalProperty($instance->name, $instance->value);
+            }
+        } catch (\ReflectionException) {
+            // Silently fail, we'll just not have additional properties
+        }
+    }
+
     protected function generateDefinition(ClassParserInterface $class, array &$dependencies = []): ?Definition
     {
         $properties = [];
+
+        // Process class-level Definition attribute if present
+        $title = $class->getShortName();
+        $description = '';
+
+        $classDefinition = $class->findAttribute(ClassDefinition::class);
+        if ($classDefinition !== null) {
+            if (!empty($classDefinition->title)) {
+                $title = $classDefinition->title;
+            }
+
+            if (!empty($classDefinition->description)) {
+                $description = $classDefinition->description;
+            }
+        }
+
         if ($class->isEnum()) {
             return new Definition(
                 type: $class->getName(),
                 options: $class->getEnumValues(),
-                title: $class->getShortName(),
+                title: $title,
+                description: $description,
             );
         }
 
@@ -102,7 +169,12 @@ protected function generateDefinition(ClassParserInterface $class, array &$depen
             $properties[$property->getName()] = $psc;
         }
 
-        return new Definition(type: $class->getName(), title: $class->getShortName(), properties: $properties);
+        return new Definition(
+            type: $class->getName(),
+            title: $title,
+            description: $description,
+            properties: $properties,
+        );
     }
 
     protected function generateProperty(PropertyInterface $property): ?Property

src/Parser/ClassParser.php

@@ -98,6 +98,17 @@ public function getProperties(): array
         return $properties;
     }
 
+    public function findAttribute(string $name): ?object
+    {
+        $attributes = $this->class->getAttributes($name);
+
+        if ($attributes === []) {
+            return null;
+        }
+
+        return $attributes[0]->newInstance();
+    }
+
     public function isEnum(): bool
     {
         return $this->class->isEnum();

src/Parser/ClassParserInterface.php

@@ -24,4 +24,15 @@ public function getProperties(): array;
     public function isEnum(): bool;
 
     public function getEnumValues(): array;
+
+    /**
+     * Find a class-level attribute.
+     *
+     * @template T
+     *
+     * @param class-string<T> $name The class name of the attribute.
+     *
+     * @return T|null The attribute or {@see null}, if the requested attribute does not exist.
+     */
+    public function findAttribute(string $name): ?object;
 }

src/Schema.php

@@ -9,17 +9,73 @@
 final class Schema extends AbstractDefinition
 {
     private array $definitions = [];
+    private string $title = '';
+    private string $description = '';
+    private ?string $id = null;
+    private ?string $schemaVersion = null;
+    private array $additionalProperties = [];
 
     public function addDefinition(string $name, Definition $definition): self
     {
         $this->definitions[$name] = $definition;
         return $this;
     }
 
+    public function setTitle(string $title): self
+    {
+        $this->title = $title;
+        return $this;
+    }
+
+    public function setDescription(string $description): self
+    {
+        $this->description = $description;
+        return $this;
+    }
+
+    public function setId(?string $id): self
+    {
+        $this->id = $id;
+        return $this;
+    }
+
+    public function setSchemaVersion(?string $schemaVersion): self
+    {
+        $this->schemaVersion = $schemaVersion;
+        return $this;
+    }
+
+    public function addAdditionalProperty(string $name, mixed $value): self
+    {
+        $this->additionalProperties[$name] = $value;
+        return $this;
+    }
+
     public function jsonSerialize(): array
     {
         $schema = $this->renderProperties([]);
 
+        if ($this->title !== '') {
+            $schema['title'] = $this->title;
+        }
+
+        if ($this->description !== '') {
+            $schema['description'] = $this->description;
+        }
+
+        if ($this->id !== null) {
+            $schema['$id'] = $this->id;
+        }
+
+        if ($this->schemaVersion !== null) {
+            $schema['$schema'] = $this->schemaVersion;
+        }
+
+        // Add any additional properties that were specified
+        foreach ($this->additionalProperties as $key => $value) {
+            $schema[$key] = $value;
+        }
+
         if ($this->definitions !== []) {
             $schema['definitions'] = [];