add id schema and content methods

tymondesigns · tymondesigns · commit 27238e67dcda · 2026-02-05T09:13:44.000Z
diff --git a/docs/json-schema/schema-types/string.mdx b/docs/json-schema/schema-types/string.mdx
@@ -147,6 +147,55 @@ $timeSchema = Schema::string('appointment_time')
 Formats marked with † require JSON Schema Draft-07 or later. Formats marked with * require Draft 2019-09 or later.
 </Note>
 
+## Content Annotations
+
+Describe encoded content carried by a string using `contentEncoding` and `contentMediaType`, and (optionally) validate the decoded content with `contentSchema`:
+
+```php
+use Cortex\JsonSchema\Enums\SchemaVersion;
+use Cortex\JsonSchema\Enums\SchemaFormat;
+
+$payloadSchema = Schema::string('payload', SchemaVersion::Draft_2019_09)
+    ->contentEncoding('base64')
+    ->contentMediaType('application/json')
+    ->contentSchema(
+        Schema::object()
+            ->properties(
+                Schema::string('event_id')->required(),
+                Schema::string('type')->required(),
+                Schema::string('created_at')->format(SchemaFormat::DateTime)->required(),
+                Schema::object('data')
+                    ->properties(
+                        Schema::string('user_id')->required(),
+                        Schema::string('email')->format(SchemaFormat::Email),
+                    )
+                    ->required(),
+            ),
+    );
+```
+
+<Note>
+`contentSchema` requires JSON Schema Draft 2019-09 or later. `contentEncoding` and `contentMediaType` are available in all supported versions.
+</Note>
+
+Validation examples:
+
+```php
+$payloadSchema->isValid(base64_encode(
+    json_encode([
+        'event_id' => 'evt_123',
+        'type' => 'user.created',
+        'created_at' => '2024-03-14T12:00:00Z',
+        'data' => [
+            'user_id' => 'usr_1',
+            'email' => 'ada@example.com',
+        ],
+    ], JSON_THROW_ON_ERROR),
+)); // true (base64 encoded string value and matches the content schema)
+
+$payloadSchema->isValid(123); // false (not a string)
+```
+
 ## Enumeration Values
 
 Restrict strings to a specific set of allowed values:
@@ -196,6 +245,10 @@ $passwordSchema = Schema::string('password')
     ->pattern('(?=.*[a-z])(?=.*[A-Z])(?=.*\d)');
 ```
 
+<Note>
+Read-only and write-only annotations require JSON Schema Draft-07 or later.
+</Note>
+
 ## Complex Example
 
 Here's a comprehensive example combining multiple string validation features:
diff --git a/src/Converters/JsonConverter.php b/src/Converters/JsonConverter.php
@@ -18,6 +18,7 @@
 use Cortex\JsonSchema\Types\BooleanSchema;
 use Cortex\JsonSchema\Types\IntegerSchema;
 use Cortex\JsonSchema\Contracts\JsonSchema;
+use Cortex\JsonSchema\Types\AbstractSchema;
 use Cortex\JsonSchema\Exceptions\SchemaException;
 
 class JsonConverter implements Converter
@@ -149,6 +150,16 @@ private function getConstValue(string $key): bool|float|int|string|null
         return null;
     }
 
+    /**
+     * Apply shared fields to the schema.
+     */
+    private function applyId(AbstractSchema $schema): void
+    {
+        if (($id = $this->getString('$id')) !== null) {
+            $schema->id($id);
+        }
+    }
+
     /**
      * Detect schema version from $schema URI.
      */
@@ -166,6 +177,7 @@ private function detectSchemaVersion(string $schemaUri): SchemaVersion
     private function createStringSchema(?string $title): StringSchema
     {
         $stringSchema = new StringSchema($title, $this->schemaVersion);
+        $this->applyId($stringSchema);
 
         if (($minLength = $this->getInt('minLength')) !== null) {
             $stringSchema->minLength($minLength);
@@ -179,6 +191,23 @@ private function createStringSchema(?string $title): StringSchema
             $stringSchema->pattern($pattern);
         }
 
+        if (($contentEncoding = $this->getString('contentEncoding')) !== null) {
+            $stringSchema->contentEncoding($contentEncoding);
+        }
+
+        if (($contentMediaType = $this->getString('contentMediaType')) !== null) {
+            $stringSchema->contentMediaType($contentMediaType);
+        }
+
+        $contentSchema = $this->getValue('contentSchema');
+
+        if (is_array($contentSchema)) {
+            $converter = new self($contentSchema, $this->schemaVersion);
+            $stringSchema->contentSchema($converter->convert());
+        } elseif (is_bool($contentSchema)) {
+            $stringSchema->contentSchema($contentSchema);
+        }
+
         if (($format = $this->getString('format')) !== null) {
             $stringSchema->format($format);
         }
@@ -218,6 +247,7 @@ private function createStringSchema(?string $title): StringSchema
     private function createNumberSchema(?string $title): NumberSchema
     {
         $numberSchema = new NumberSchema($title, $this->schemaVersion);
+        $this->applyId($numberSchema);
 
         if (($minimum = $this->getFloat('minimum')) !== null) {
             $numberSchema->minimum($minimum);
@@ -262,6 +292,7 @@ private function createNumberSchema(?string $title): NumberSchema
     private function createIntegerSchema(?string $title): IntegerSchema
     {
         $integerSchema = new IntegerSchema($title, $this->schemaVersion);
+        $this->applyId($integerSchema);
 
         if (($minimum = $this->getInt('minimum')) !== null) {
             $integerSchema->minimum($minimum);
@@ -306,6 +337,7 @@ private function createIntegerSchema(?string $title): IntegerSchema
     private function createBooleanSchema(?string $title): BooleanSchema
     {
         $booleanSchema = new BooleanSchema($title, $this->schemaVersion);
+        $this->applyId($booleanSchema);
 
         if (($const = $this->getConstValue('const')) !== null) {
             $booleanSchema->const($const);
@@ -329,6 +361,7 @@ private function createBooleanSchema(?string $title): BooleanSchema
     private function createArraySchema(?string $title): ArraySchema
     {
         $arraySchema = new ArraySchema($title, $this->schemaVersion);
+        $this->applyId($arraySchema);
 
         if (($items = $this->getArray('items')) !== null) {
             $converter = new self($items, $this->schemaVersion);
@@ -372,6 +405,7 @@ private function createArraySchema(?string $title): ArraySchema
     private function createObjectSchema(?string $title): ObjectSchema
     {
         $objectSchema = new ObjectSchema($title, $this->schemaVersion);
+        $this->applyId($objectSchema);
         $required = $this->getArray('required') ?? [];
 
         if (($properties = $this->getArray('properties')) !== null) {
@@ -434,6 +468,7 @@ private function createObjectSchema(?string $title): ObjectSchema
     private function createNullSchema(?string $title): NullSchema
     {
         $nullSchema = new NullSchema($title, $this->schemaVersion);
+        $this->applyId($nullSchema);
 
         if (($description = $this->getString('description')) !== null) {
             $nullSchema->description($description);
@@ -461,6 +496,8 @@ private function createUnionSchema(?string $title): UnionSchema
             $schema = new UnionSchema(SchemaType::cases(), $title, $this->schemaVersion);
         }
 
+        $this->applyId($schema);
+
         if (($enum = $this->getArray('enum')) !== null && $enum !== []) {
             /** @var non-empty-array<bool|float|int|string|null> $enum */
             $schema->enum($enum);
diff --git a/src/Types/AbstractSchema.php b/src/Types/AbstractSchema.php
@@ -7,6 +7,7 @@
 use Cortex\JsonSchema\Enums\SchemaType;
 use Cortex\JsonSchema\Enums\SchemaVersion;
 use Cortex\JsonSchema\Contracts\JsonSchema;
+use Cortex\JsonSchema\Types\Concerns\HasId;
 use Cortex\JsonSchema\Types\Concerns\HasRef;
 use Cortex\JsonSchema\Types\Concerns\HasEnum;
 use Cortex\JsonSchema\Types\Concerns\HasConst;
@@ -25,6 +26,7 @@
 abstract class AbstractSchema implements JsonSchema
 {
     use HasRef;
+    use HasId;
     use HasEnum;
     use HasConst;
     use HasTitle;
@@ -113,6 +115,7 @@ public function toArray(bool $includeSchemaRef = true, bool $includeTitle = true
             $schema['$schema'] = $this->schemaVersion->value;
         }
 
+        $schema = $this->addIdToSchema($schema);
         $schema = $this->addTitleToSchema($schema, $includeTitle);
         $schema = $this->addFormatToSchema($schema);
         $schema = $this->addDescriptionToSchema($schema);
diff --git a/src/Types/Concerns/HasId.php b/src/Types/Concerns/HasId.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cortex\JsonSchema\Types\Concerns;
+
+/** @mixin \Cortex\JsonSchema\Contracts\JsonSchema */
+trait HasId
+{
+    protected ?string $id = null;
+
+    /**
+     * Set the $id value for this schema.
+     */
+    public function id(string $id): static
+    {
+        $this->id = $id;
+
+        return $this;
+    }
+
+    /**
+     * Get the $id value for this schema.
+     */
+    public function getId(): ?string
+    {
+        return $this->id;
+    }
+
+    /**
+     * Add $id to schema array.
+     *
+     * @param array<string, mixed> $schema
+     *
+     * @return array<string, mixed>
+     */
+    protected function addIdToSchema(array $schema): array
+    {
+        if ($this->id !== null) {
+            $schema['$id'] = $this->id;
+        }
+
+        return $schema;
+    }
+}
diff --git a/src/Types/Concerns/HasValidation.php b/src/Types/Concerns/HasValidation.php
@@ -23,6 +23,7 @@ public function validate(mixed $value): void
     {
         $validator = new Validator();
         $validator->parser()->setOption('defaultDraft', '2020-12');
+        $validator->parser()->setOption('decodeContent', true);
 
         try {
             $result = $validator->validate(
diff --git a/src/Types/StringSchema.php b/src/Types/StringSchema.php
@@ -6,7 +6,9 @@
 
 use Override;
 use Cortex\JsonSchema\Enums\SchemaType;
+use Cortex\JsonSchema\Enums\SchemaFeature;
 use Cortex\JsonSchema\Enums\SchemaVersion;
+use Cortex\JsonSchema\Contracts\JsonSchema;
 use Cortex\JsonSchema\Exceptions\SchemaException;
 
 final class StringSchema extends AbstractSchema
@@ -17,6 +19,12 @@ final class StringSchema extends AbstractSchema
 
     protected ?string $pattern = null;
 
+    protected ?string $contentEncoding = null;
+
+    protected ?string $contentMediaType = null;
+
+    protected JsonSchema|bool|null $contentSchema = null;
+
     public function __construct(?string $title = null, ?SchemaVersion $schemaVersion = null)
     {
         parent::__construct(SchemaType::String, $title, $schemaVersion);
@@ -66,6 +74,37 @@ public function pattern(string $pattern): static
         return $this;
     }
 
+    /**
+     * Set the content encoding.
+     */
+    public function contentEncoding(string $contentEncoding): static
+    {
+        $this->contentEncoding = $contentEncoding;
+
+        return $this;
+    }
+
+    /**
+     * Set the content media type.
+     */
+    public function contentMediaType(string $contentMediaType): static
+    {
+        $this->contentMediaType = $contentMediaType;
+
+        return $this;
+    }
+
+    /**
+     * Set the content schema.
+     */
+    public function contentSchema(JsonSchema|bool $contentSchema): static
+    {
+        $this->validateFeatureSupport(SchemaFeature::ContentSchema);
+        $this->contentSchema = $contentSchema;
+
+        return $this;
+    }
+
     /**
      * Convert to array.
      *
@@ -76,7 +115,31 @@ public function toArray(bool $includeSchemaRef = true, bool $includeTitle = true
     {
         $schema = parent::toArray($includeSchemaRef, $includeTitle);
 
-        return $this->addLengthToSchema($schema);
+        $schema = $this->addLengthToSchema($schema);
+
+        return $this->addContentToSchema($schema);
+    }
+
+    /**
+     * Get features used by this schema from all traits.
+     *
+     * @return array<\Cortex\JsonSchema\Enums\SchemaFeature>
+     */
+    #[Override]
+    protected function getUsedFeatures(): array
+    {
+        $features = [
+            ...parent::getUsedFeatures(),
+            ...$this->getContentFeatures(),
+        ];
+
+        $uniqueFeatures = [];
+
+        foreach ($features as $feature) {
+            $uniqueFeatures[$feature->value] = $feature;
+        }
+
+        return array_values($uniqueFeatures);
     }
 
     /**
@@ -102,4 +165,46 @@ protected function addLengthToSchema(array $schema): array
 
         return $schema;
     }
+
+    /**
+     * Add content keywords to schema array.
+     *
+     * @param array<string, mixed> $schema
+     *
+     * @return array<string, mixed>
+     */
+    protected function addContentToSchema(array $schema): array
+    {
+        if ($this->contentEncoding !== null) {
+            $schema['contentEncoding'] = $this->contentEncoding;
+        }
+
+        if ($this->contentMediaType !== null) {
+            $schema['contentMediaType'] = $this->contentMediaType;
+        }
+
+        if ($this->contentSchema !== null) {
+            $schema['contentSchema'] = $this->contentSchema instanceof JsonSchema
+                ? $this->contentSchema->toArray(includeSchemaRef: false, includeTitle: false)
+                : $this->contentSchema;
+        }
+
+        return $schema;
+    }
+
+    /**
+     * Get content features used by this schema.
+     *
+     * @return array<\Cortex\JsonSchema\Enums\SchemaFeature>
+     */
+    protected function getContentFeatures(): array
+    {
+        $features = [];
+
+        if ($this->contentSchema !== null) {
+            $features[] = SchemaFeature::ContentSchema;
+        }
+
+        return $features;
+    }
 }
diff --git a/tests/Unit/Converters/JsonConverterTest.php b/tests/Unit/Converters/JsonConverterTest.php
diff --git a/tests/Unit/IdSchemaTest.php b/tests/Unit/IdSchemaTest.php
diff --git a/tests/Unit/Types/StringSchemaTest.php b/tests/Unit/Types/StringSchemaTest.php

Original file line number	Diff line number	Diff line change
`@@ -23,6 +23,7 @@ public function validate(mixed $value): void`
`23`	`23`	`{`
`24`	`24`	`$validator = new Validator();`
`25`	`25`	`$validator->parser()->setOption('defaultDraft', '2020-12');`
	`26`	`+ $validator->parser()->setOption('decodeContent', true);`
`26`	`27`
`27`	`28`	`try {`
`28`	`29`	`$result = $validator->validate(`