JSON Schema Support

JSON Schema is a popular vocabulary to describe the shape of JSON documents. A variant of JSON Schema is also used in OpenAPI specifications.

JSON スキーマは、JSON ドキュメントの形状を記述するための一般的な語彙です。 JSON スキーマのバリアントは、OpenAPI 仕様でも使用されています。

API Platform provides an infrastructure to generate JSON Schemas for any resource, represented in any format (including JSON-LD). The generated schema can be used with libraries such as react-json-schema-form to build forms for the documented resources, or to be used for validation.

API プラットフォームは、任意の形式 (JSON-LD を含む) で表される任意のリソースの JSON スキーマを生成するためのインフラストラクチャを提供します。検証に使用します。

Generating a JSON Schema

To export the schema corresponding to an API Resource, run the following command:

API リソースに対応するスキーマをエクスポートするには、次のコマンドを実行します。

docker compose exec php \
    bin/console api:json-schema:generate 'App\Entity\Book'

To see all options available, try:


docker compose exec php \
    bin/console help api:json-schema:generate

Overriding the JSON Schema Specification

In a unit testing context, API Platform does not use the same schema version as the schema used when generating the API documentation. The version used by the documentation is the OpenAPI Schema version and the version used by unit testing is the JSON Schema version.

単体テストのコンテキストでは、API プラットフォームは、API ドキュメントの生成時に使用されたスキーマと同じスキーマ バージョンを使用しません。ドキュメントで使用されるバージョンは OpenAPI スキーマ バージョンであり、単体テストで使用されるバージョンは JSON スキーマ バージョンです。

When Testing the API, JSON Schemas are useful to generate and automate unit testing. API Platform provides specific unit testing functionalities like assertMatchesResourceCollectionJsonSchema() or assertMatchesResourceItemJsonSchema() methods. These methods generate a JSON Schema then do unit testing based on the generated schema automatically.

API をテストする場合、JSON スキーマは単体テストの生成と自動化に役立ちます。 API プラットフォームは、assertMatchesResourceCollectionJsonSchema() メソッドや assertMatchesResourceItemJsonSchema() メソッドなどの特定の単体テスト機能を提供します。これらのメソッドは JSON スキーマを生成し、生成されたスキーマに基づいて単体テストを自動的に実行します。

Usually, the fact that API Platform uses a different schema version for unit testing is not a problem, but sometimes you may need to use the ApiProperty attribute to specify a calculated field type by overriding the OpenAPI Schema for the calculated field to be correctly documented.

通常、API プラットフォームが単体テストに別のスキーマ バージョンを使用することは問題ではありませんが、ApiProperty 属性を使用して、計算フィールドの OpenAPI スキーマをオーバーライドして計算フィールド タイプを指定し、正しくドキュメント化する必要がある場合があります。

When you will use assertMatchesResourceCollectionJsonSchema() or assertMatchesResourceItemJsonSchema() functions the unit test will fail on this calculated field as the unit testing process doesn't use the openapi_context you specified because API Platform is using the JSON Schema version instead at this moment.

assertMatchesResourceCollectionJsonSchema() または assertMatchesResourceItemJsonSchema() 関数を使用する場合、ユニット テスト プロセスは指定した openapi_context を使用しないため、ユニット テストはこの計算フィールドで失敗します。これは、現時点では API プラットフォームが代わりに JSON スキーマ バージョンを使用しているためです。

So there is a way to override JSON Schema specification for a specific property in the JSON Schema used by the unit testing process.

そのため、単体テスト プロセスで使用される JSON スキーマの特定のプロパティの JSON スキーマ仕様をオーバーライドする方法があります。

You will need to add the json_schema_context property in the ApiProperty attribute to do this, example:

これを行うには、ApiProperty 属性に json_schema_context プロパティを追加する必要があります。例:


namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;

class Greeting
    #[ORM\Id, ORM\Column, ORM\GeneratedValue]
    private ?int $id = null;

    // [...]

    public function getId(): ?int
        return $this->id;

        openapiContext: [
            'type' => 'array',
            'items' => ['type' => 'integer']
        jsonSchemaContext: [
            'type' => 'array',
            'items' => ['type' => 'integer']
    public function getSomeNumbers(): array {
        return [1, 2, 3, 4];

You can obtain more information about the available JSON Schema Types and format here.

利用可能な JSON スキーマ タイプと形式の詳細については、こちらを参照してください。

Generating a JSON Schema Programmatically

To generate JSON Schemas programmatically, use the api_platform.json_schema.schema_factory service.

プログラムで JSON スキーマを生成するには、api_platform.json_schema.schema_factory サービスを使用します。


API Platform provides a PHPUnit assertion to test if a response is valid according to a given Schema: assertMatchesJsonSchema(). Refer to the testing documentation for more details.

API プラットフォームは、特定のスキーマに従って応答が有効かどうかをテストするための PHPUnit アサーションを提供します: assertMatchesJsonSchema()。詳細については、テスト ドキュメントを参照してください。