Download the PHP package basillangevin/laravel-data-json-schemas without Composer

Laravel Data classes to JSON Schemas

This package transforms spatie/laravel-data classes into JSON Schemas and includes built-in validation.

Table of Contents

Installation

Note: This package requires PHP 8.3+ and Laravel 11+.

You can install the package via composer:

Optionally, you can publish the config file with:

This is the contents of the published config file:

Quick start

The BasilLangevin\LaravelDataJsonSchemas\DataSchemas facade can transform any Spatie\LaravelData\Data class into a JSON Schema.

It includes four methods:

JsonSchema::toArray(...)

To demonstrate transforming a Data class into a JSON Schema, we'll create a simple BikeData class:

Now, we can transform this Data class into a JSON Schema (as a PHP array):

This will generate the following JSON Schema. As you can see, the JSON Schema includes descriptions and validation rules to match each property's doc block and attributes:

JsonSchema::collectToArray(...)

We can also transform Data classes into a JSON Schema array whose items are instances of the Data class:

This will generate the following JSON Schema:

Schema annotations

This package supports the title, description, and default JSON Schema annotations.

Setting the title

Data classes and their properties can have a JSON Schema title annotation which can be set three different ways (in order of precedence):

1. Using the BasilLangevin\LaravelDataJsonSchemas\Attributes\Title attribute:

2. Using the summary of a PHPDoc block (when it also has a description):

Note: This method is not currently supported on Windows Servers.

3. Using the name of the Data class:

The class name will be used as the title if no other title is set. Any "Data" suffix will be removed, and the name will be title-cased and space-separated.

For example, BikePartData will become Bike Part.

Setting the description

Data classes and their properties can have a JSON Schema description annotation which can be set four different ways (in order of precedence):

1. Using the BasilLangevin\LaravelDataJsonSchemas\Attributes\Description attribute:

2. Using the description of an @param or @var tag of a PHPDoc block:

3. Using the summary of a PHPDoc block (when it has no description):

Note: This method is not currently supported on Windows Servers.

4. Using the description of a PHPDoc block (when it also has a summary):

Note: This method is not currently supported on Windows Servers.

Setting the default value

The default JSON Schema annotation will be set to the default value of the property.

Validation rules

This package automatically transforms spatie\laravel-data validation attributes into JSON Schema keywords.

For example, the Min attribute will be transformed into a minLength keyword when the property is a string or a minimum keyword when the property is an integer:

This will generate the following JSON Schema:

Supported validation attributes

This package supports most of the validation attributes available in spatie\laravel-data, as detailed in the table below. Custom validation attributes are not supported.

Validation attributes that can be transformed into JSON Schema validation keywords are indicated with ✅.

Because JSON Schema's validation keywords are somewhat limited, some validation attributes can only be transformed into custom annotations (indicated with ☑️). These attributes cannot be validated by any JSON Schema validator, so they must be validated by Laravel's validation system.

Finally, some validation attributes are not supported at all (indicated with ❌). Typically, these attributes exceed the scope of what JSON Schema supports, or they rely on database calls to be validated.

The following table summarizes the support for each attribute, grouped by JSON Schema's type keyword rather than the PHP type equivalent.

See the Type transformations section for more details.

Date attribute transformations

Every validation attribute that validates dates (except the DateFormat attribute) sets the format keyword to date-time. Therefore, all date attributes follow the ISO 8601 standard.

Relative date attribute values (e.g. 'now', 'yesterday', 'next week', etc.) are transformed into ISO 8601 date strings.

Type transformations

JSON Schema only supports a few types (array, boolean, integer, number, object, string, and null), so this package transforms PHP types into the closest JSON Schema type.

The following types are transformed as follows. All other types are currently unsupported.

Array Arrays are transformed into the array or object type depending on whether they have sequential integer keys.

Boolean Booleans are transformed into the boolean type.

Collection Collection types (including DataCollection) are transformed into the array type.

Data Data classes are transformed into object types.

DateTimeInterface DateTimeInterface types (including DateTime, Carbon, and CarbonImmutable) are transformed into the string type.

All date schemas include the format keyword with the value date-time. Therefore, all dates follow the ISO 8601 standard.

Enum Backed enums are transformed into either the string or integer type depending on their backing type. Pure enums are not supported.

Float Floats are transformed into the number type.

Integer Integers are transformed into the integer type.

Null Nulls are transformed into the null type.

Object Objects are transformed into the object type.

String Strings are transformed into the string type.

Union Unions are transformed into a union of their constituent types. Unions that include Data types wrap their constituent type schemas in an anyOf schema. Otherwise, the constituent schemas are consolidated into a single schema.

Testing

Each PHP file in this package has a co-located Pest test file named {FileName}Test.php.

This package also has integration tests in the tests/Integration directory. These integration tests are used to test complex Data class transformations including nested Data classes, collections of Data objects, recursive Data structures, and complex union types.

This package achieves 100% test coverage, 100% mutation coverage, and 100% PHPStan coverage coverage at level 10.

The following commands can be used to test the package:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• BasilLangevin
• All Contributors

License

The MIT License (MIT). Please see License File for more information.