fix: Ensure object properties can have a different title (#21)

Author: tymondesigns

.github/workflows/static-analysis.yml

@@ -70,4 +70,4 @@ jobs:
             ecs-cache-
 
       - name: Run format checks
-        run: composer format --no-progress-bar
+        run: composer format:check --no-progress-bar

composer.json

@@ -44,13 +44,19 @@
     "scripts": {
         "test": "pest",
         "ecs": "ecs check --fix",
+        "ecs:check": "ecs check",
         "rector": "rector process",
+        "rector:check": "rector process --dry-run",
         "stan": "phpstan analyse",
         "type-coverage": "pest --type-coverage --min=100",
         "format": [
             "@rector",
             "@ecs"
         ],
+        "format:check": [
+            "@rector:check",
+            "@ecs:check"
+        ],
         "check": [
             "@format",
             "@test",

docs/json-schema/schema-types/object.mdx

@@ -103,6 +103,29 @@ $productSchema = Schema::object('product')
 ```
 </Accordion>
 
+## Property Titles
+
+Property names are defined by the schema constructor argument, while `title()` is metadata and only included when it differs from the property name:
+
+```php
+$schema = Schema::object()
+    ->properties(
+        Schema::string('email')->title('Email Address')
+    );
+```
+
+```json
+{
+    "type": "object",
+    "properties": {
+        "email": {
+            "type": "string",
+            "title": "Email Address"
+        }
+    }
+}
+```
+
 ## Required Properties
 
 Specify which properties are mandatory:

src/Contracts/JsonSchema.php

@@ -98,4 +98,9 @@ public function version(SchemaVersion $schemaVersion): static;
      * Get the JSON Schema version for this schema.
      */
     public function getVersion(): SchemaVersion;
+
+    /**
+     * Get the initial title.
+     */
+    public function getInitialTitle(): ?string;
 }

src/Schema.php

@@ -174,7 +174,7 @@ public static function from(
             // @phpstan-ignore argument.type
             is_array($value) || (is_string($value) && json_validate($value)) => self::fromJson($value, $schemaVersion),
             default => throw new SchemaException(
-                'Unsupported value type. Only closures, enums, and classes are supported.',
+                'Unsupported value type. Only closures, enums, arrays and classes are supported.',
             ),
         };
     }

src/Types/AbstractSchema.php

@@ -19,6 +19,7 @@
 use Cortex\JsonSchema\Types\Concerns\HasDefinitions;
 use Cortex\JsonSchema\Types\Concerns\HasDescription;
 use Cortex\JsonSchema\Types\Concerns\HasConditionals;
+use Cortex\JsonSchema\Types\Concerns\HasInitialTitle;
 use Cortex\JsonSchema\Types\Concerns\ValidatesVersionFeatures;
 
 abstract class AbstractSchema implements JsonSchema
@@ -33,8 +34,9 @@ abstract class AbstractSchema implements JsonSchema
     use HasReadWrite;
     use HasValidation;
     use HasDescription;
-    use HasConditionals;
     use HasDefinitions;
+    use HasConditionals;
+    use HasInitialTitle;
     use ValidatesVersionFeatures;
 
     protected SchemaVersion $schemaVersion = SchemaVersion::Draft_2020_12;
@@ -47,6 +49,7 @@ public function __construct(
         ?string $title = null,
         ?SchemaVersion $schemaVersion = null,
     ) {
+        $this->initialTitle = $title;
         $this->title = $title;
         $this->schemaVersion = $schemaVersion ?? SchemaVersion::default();
     }

src/Types/Concerns/HasInitialTitle.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cortex\JsonSchema\Types\Concerns;
+
+/** @mixin \Cortex\JsonSchema\Contracts\JsonSchema */
+trait HasInitialTitle
+{
+    protected ?string $initialTitle = null;
+
+    /**
+     * Get the initial title.
+     *
+     * @internal
+     */
+    public function getInitialTitle(): ?string
+    {
+        return $this->initialTitle;
+    }
+}

src/Types/Concerns/HasProperties.php

@@ -55,7 +55,7 @@ trait HasProperties
     public function properties(JsonSchema ...$properties): static
     {
         foreach ($properties as $property) {
-            $title = $property->getTitle();
+            $title = $this->resolvePropertyTitle($property);
 
             if ($title === null) {
                 throw new SchemaException('Property must have a title');
@@ -254,7 +254,7 @@ public function hasRequiredProperties(): bool
     public function requireAll(): static
     {
         foreach ($this->properties as $property) {
-            $title = $property->getTitle();
+            $title = $this->resolvePropertyTitle($property);
 
             if ($title !== null) {
                 $this->requiredProperties[] = $title;
@@ -277,7 +277,15 @@ protected function addPropertiesToSchema(array $schema): array
             $schema['properties'] = [];
 
             foreach ($this->properties as $name => $prop) {
-                $schema['properties'][$name] = $prop->toArray(includeSchemaRef: false, includeTitle: false);
+                $propertySchema = $prop->toArray(includeSchemaRef: false, includeTitle: true);
+
+                // If the property schema has a title and it matches the name,
+                // then we don't need to include it in the schema
+                if (array_key_exists('title', $propertySchema) && $propertySchema['title'] === $name) {
+                    unset($propertySchema['title']);
+                }
+
+                $schema['properties'][$name] = $propertySchema;
             }
         }
 
@@ -331,6 +339,14 @@ protected function addPropertiesToSchema(array $schema): array
         return $schema;
     }
 
+    /**
+     * Resolve the property title from a schema instance.
+     */
+    protected function resolvePropertyTitle(JsonSchema $jsonSchema): ?string
+    {
+        return $jsonSchema->getInitialTitle() ?? $jsonSchema->getTitle();
+    }
+
     /**
      * Get unevaluated properties features used by this schema.
      *

tests/Unit/Types/ObjectSchemaTest.php

@@ -113,6 +113,21 @@
     }
 })->throws(SchemaException::class);
 
+it('can set the property title separately from the property key', function (): void {
+    $objectSchema = Schema::object()
+        ->properties(
+            Schema::string('foo')->title('Foo'),
+            Schema::string('bar'),
+        );
+
+    $schemaArray = $objectSchema->toArray();
+
+    expect($schemaArray)->toHaveKey('properties.foo.type', 'string');
+    expect($schemaArray)->toHaveKey('properties.foo.title', 'Foo');
+    expect($schemaArray)->toHaveKey('properties.bar.type', 'string');
+    expect($schemaArray['properties']['bar'])->not->toHaveKey('title');
+});
+
 it('can create an object schema with additional properties control', function (): void {
     $objectSchema = Schema::object('config')
         ->description('Configuration object')