README

A Symfony bundle that integrates JSON Schema validation with API Platform's OpenAPI documentation. This bundle allows you to dynamically populate OpenAPI schemas for JSON fields by aggregating schemas from multiple providers.

Features

Dynamic JSON Schema Integration: Automatically inject JSON schemas into API Platform OpenAPI documentation
Multiple Schema Providers: Aggregate schemas from multiple sources using a registry pattern
anyOf Schema Composition: Combine multiple schemas into a unified schema with JSON Schema's anyOf
PHP 8 Attributes: Use simple #[JsonSchema] attribute to mark JSON fields for schema integration
Entity-Level Schema Control: Entities can provide dynamic schemas via JsonSchemaProviderInterface
Auto-Discovery: Schema providers are automatically registered via Symfony's service tagging
Caching: Built-in caching for unified schemas to improve performance
Configurable: Schema base path and cache TTL are configurable

Installation

1. Add to composer.json

Since this is an internal bundle in the extensions/ directory, add autoloading in your composer.json:

{
    "autoload": {
        "psr-4": {
            "Schmunk42\\OpenApiJsonSchema\\": "extensions/openapi-json-schema-bundle/src/"
        }
    }
}

Run composer dump-autoload:

composer dump-autoload

2. Register Bundle

Add the bundle to config/bundles.php:

return [
    // ...
    Schmunk42\OpenApiJsonSchema\Schmunk42OpenApiJsonSchemaBundle::class => ['all' => true],
];

3. Configure (Optional)

Create config/packages/schmunk42_open_api_json_schema.yaml:

schmunk42_open_api_json_schema:
    schema_base_path: '%kernel.project_dir%/config/schemas'  # Default
    cache_ttl: 3600  # Cache TTL in seconds (default: 1 hour)

Basic Usage

Simple Example: Tags Array

Here's a simple example of adding JSON schema validation to a tags field:

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Schmunk42\OpenApiJsonSchema\Attribute\JsonSchema;

#[ApiResource]
#[ORM\Entity]
class Article
{
    #[ORM\Id]
    #[ORM\Column(type: 'string')]
    private string $id;

    #[ORM\Column(type: 'string')]
    private string $title;

    #[ORM\Column(type: 'json')]
    #[JsonSchema('article-tags.json')]
    private array $tags = [];
}

Create config/schemas/article-tags.json:

{
    "$schema": "https://json-schema.org/draft-07/schema#",
    "type": "array",
    "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 50
    },
    "uniqueItems": true,
    "maxItems": 10
}

The Power of the Annotation

Key Concept: #[ORM\Column(type: 'json')] + #[JsonSchema] = Full JSON Schema in OpenAPI

The bundle automatically injects your JSON schema into the OpenAPI documentation. This means:

Your database column stores validated JSON data
Your API documentation shows the exact schema structure
Clients can see what data structure is expected

IMPORTANT: Including schemas this way still produces fully valid JSON schemas, which are fully compatible with OpenAPI 3.1.

OpenAPI Output

With the example above, your OpenAPI schema will include:

{
  "Article": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "title": {
        "type": "string"
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        },
        "uniqueItems": true,
        "maxItems": 10
      }
    }
  }
}

Dynamic Schemas from Entity Method

For schemas that require runtime logic, use the #[JsonSchema] attribute without a path and implement JsonSchemaProviderInterface:

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Schmunk42\OpenApiJsonSchema\Attribute\JsonSchema;
use Schmunk42\OpenApiJsonSchema\Interface\JsonSchemaProviderInterface;

#[ApiResource]
#[ORM\Entity]
class Report implements JsonSchemaProviderInterface
{
    #[ORM\Id]
    #[ORM\Column(type: 'string')]
    private string $id;

    #[ORM\Column(type: 'json')]
    #[JsonSchema]  // No path - uses getJsonSchema() method
    private array $filters = [];

    public static function getJsonSchema(string $fieldName): ?array
    {
        if ($fieldName === 'filters') {
            $firstDayOfMonth = (new \DateTime('first day of this month'))->format('Y-m-d');

            return [
                'type' => 'object',
                'properties' => [
                    'dateFrom' => [
                        'type' => 'string',
                        'format' => 'date',
                        'default' => $firstDayOfMonth,
                        'description' => 'Start date for report (defaults to first day of current month)'
                    ],
                    'dateTo' => [
                        'type' => 'string',
                        'format' => 'date',
                        'description' => 'End date for report'
                    ]
                ],
                'required' => ['dateFrom', 'dateTo']
            ];
        }
        return null;
    }
}

This approach is useful when:

Schema needs runtime-calculated values (like dates)
Schema structure depends on application state
You want to keep schema logic close to the entity

Advanced Usage

For complex scenarios including:

Creating schema providers for unified schemas
Schema validation
Cache management
Using unified schemas in entities

See Advanced Usage Documentation

Architecture

Components

SchemaRegistry (Service/SchemaRegistry.php)
- Central registry for schema providers
- Aggregates schemas into unified anyOf structure
- Handles caching
JsonFieldSchemaDecorator (OpenApi/JsonFieldSchemaDecorator.php)
- Decorates API Platform's schema factory
- Processes #[JsonSchema] attributes
- Injects schemas into OpenAPI documentation
Interfaces
- SchemaProviderInterface: For external schema sources
- JsonSchemaProviderInterface: For entity-level dynamic schemas
Attribute
- #[JsonSchema]: Marks fields for schema injection

How It Works

Service Registration: Schema providers implementing SchemaProviderInterface are auto-tagged with schmunk42_open_api_json_schema.provider
Registry Population: SchemaRegistry receives all tagged providers via tagged iterator
Schema Aggregation: When getUnifiedSchema() is called, registry loads all provider schemas and combines them using anyOf
OpenAPI Integration: JsonFieldSchemaDecorator decorates API Platform's schema factory and processes entities during OpenAPI generation
Attribute Processing: Fields with #[JsonSchema] attribute get their schema from:
- File path (if provided in attribute)
- Entity's getJsonSchema() method (if implements JsonSchemaProviderInterface)
- SchemaRegistry (if entity uses unified schema)

Requirements

PHP 8.1+
Symfony 7.0+
API Platform 3.0+
opis/json-schema (for validation)

License

Proprietary - herzog kommunikation GmbH

Credits

Developed for the ZA7 (Zentrales Agentursystem Version 7) project.

schmunk42 / openapi-json-schema-bundle

Maintainers

Details