PHPackages                             schmunk42/openapi-json-schema-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. schmunk42/openapi-json-schema-bundle

ActiveSymfony-bundle[API Development](/categories/api)

schmunk42/openapi-json-schema-bundle
====================================

Symfony bundle for integrating JSON Schema validation with API Platform OpenAPI documentation via dynamic schema aggregation

11[2 issues](https://github.com/schmunk42/openapi-json-schema-bundle/issues)PHP

Since Nov 23Pushed 5mo agoCompare

[ Source](https://github.com/schmunk42/openapi-json-schema-bundle)[ Packagist](https://packagist.org/packages/schmunk42/openapi-json-schema-bundle)[ RSS](/packages/schmunk42-openapi-json-schema-bundle/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (1)Used By (0)

schmunk42 OpenAPI JSON Schema Bundle
====================================

[](#schmunk42-openapi-json-schema-bundle)

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
--------

[](#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
------------

[](#installation)

### 1. Add to composer.json

[](#1-add-to-composerjson)

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

[](#2-register-bundle)

Add the bundle to `config/bundles.php`:

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

### 3. Configure (Optional)

[](#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
-----------

[](#basic-usage)

### Simple Example: Tags Array

[](#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

[](#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

[](#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

[](#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
--------------

[](#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](docs/advanced-usage.md)

Architecture
------------

[](#architecture)

### Components

[](#components)

1. **SchemaRegistry** (`Service/SchemaRegistry.php`)

    - Central registry for schema providers
    - Aggregates schemas into unified `anyOf` structure
    - Handles caching
2. **JsonFieldSchemaDecorator** (`OpenApi/JsonFieldSchemaDecorator.php`)

    - Decorates API Platform's schema factory
    - Processes `#[JsonSchema]` attributes
    - Injects schemas into OpenAPI documentation
3. **Interfaces**

    - `SchemaProviderInterface`: For external schema sources
    - `JsonSchemaProviderInterface`: For entity-level dynamic schemas
4. **Attribute**

    - `#[JsonSchema]`: Marks fields for schema injection

### How It Works

[](#how-it-works)

1. **Service Registration**: Schema providers implementing `SchemaProviderInterface` are auto-tagged with `schmunk42_open_api_json_schema.provider`
2. **Registry Population**: `SchemaRegistry` receives all tagged providers via tagged iterator
3. **Schema Aggregation**: When `getUnifiedSchema()` is called, registry loads all provider schemas and combines them using `anyOf`
4. **OpenAPI Integration**: `JsonFieldSchemaDecorator` decorates API Platform's schema factory and processes entities during OpenAPI generation
5. **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
------------

[](#requirements)

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

License
-------

[](#license)

Proprietary - herzog kommunikation GmbH

Credits
-------

[](#credits)

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

###  Health Score

13

—

LowBetter than 1% of packages

Maintenance28

Infrequent updates — may be unmaintained

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/3b4ab2b6685ec71887908ec8cff261a16cd5bb24c69bb8ab52840e220f175f9d?d=identicon)[schmunk](/maintainers/schmunk)

---

Top Contributors

[![schmunk42](https://avatars.githubusercontent.com/u/649031?v=4)](https://github.com/schmunk42 "schmunk42 (3 commits)")

### Embed Badge

![Health badge](/badges/schmunk42-openapi-json-schema-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/schmunk42-openapi-json-schema-bundle/health.svg)](https://phpackages.com/packages/schmunk42-openapi-json-schema-bundle)
```

###  Alternatives

[stripe/stripe-php

Stripe PHP Library

4.0k143.3M480](/packages/stripe-stripe-php)[twilio/sdk

A PHP wrapper for Twilio's API

1.6k92.9M272](/packages/twilio-sdk)[facebook/php-business-sdk

PHP SDK for Facebook Business

90821.9M34](/packages/facebook-php-business-sdk)[meilisearch/meilisearch-php

PHP wrapper for the Meilisearch API

74513.7M114](/packages/meilisearch-meilisearch-php)[google/gax

Google API Core for PHP

265103.1M454](/packages/google-gax)[google/common-protos

Google API Common Protos for PHP

173103.7M50](/packages/google-common-protos)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)