---
title: "JSON Schema builder and hydrator"
description: "Describe PHP types as JSON Schema with the SchemaBuilder, and change raw data into PHP values with the Hydrator."
canonical: json-schema.html
navigation-title: "JSON Schema"
---

<a id="developer-json-schema"></a>

<a id="json-schema-builder-and-hydrator"></a>

# JSON Schema builder and hydrator

`\TYPO3\CMS\Core\JsonSchema\SchemaBuilder` creates the JSON Schema of
actions. You can also use it alone, to describe PHP types for external systems.
It creates an immutable `\TYPO3\CMS\Core\JsonSchema\Schema` from a PHP
type of `symfony/type-info`. It supports scalars, lists, maps, array shapes,
unions, intersections, enums, implementations of `\DateTimeInterface`, data
objects with their promoted constructor properties, and generic data objects
with `@template` annotations. A `\TYPO3\CMS\Core\JsonSchema\SchemaStore`
collects the definitions of objects, and a schema refers to them with
`$ref`. This allows circular structures.

`\TYPO3\CMS\Core\JsonSchema\Hydrator` uses such a schema to change raw
data, for example from `json_decode()`, into the described PHP values.
This includes enums, `\DateTimeImmutable` instances and data objects.

```php
use Symfony\Component\TypeInfo\Type;
use TYPO3\CMS\Core\JsonSchema\Hydrator;
use TYPO3\CMS\Core\JsonSchema\SchemaBuilder;

final readonly class Coordinates
{
    public function __construct(
        public float $latitude,
        public float $longitude,
        public ?string $label = null,
    ) {}
}

$schema = (new SchemaBuilder())->build(Type::object(Coordinates::class));

// Expose the schema to an external system
$json = json_encode($schema);

// Hydrate raw input data based on the schema
$coordinates = (new Hydrator())->hydrate(
    json_decode('{"latitude": 50.9, "longitude": 6.9}'),
    $schema,
);
```

The PHP attributes
`\TYPO3\CMS\Core\Attribute\Serialization\IntersectWithParent` and
`\TYPO3\CMS\Core\Attribute\Serialization\DynamicSerializationSchema`
control how a schema shows nested data objects. With
`\TYPO3\CMS\Core\JsonSchema\DynamicSchemaProviderInterface`, you can supply
schemas that TYPO3 knows only at runtime.