README

json-schema-php is an object-oriented PHP library for generating JSON Schema documents (Draft-07).

It allows you to programmatically build JSON schemas using a fluent, expressive API — no need to manually write arrays or JSON.

Features

Full support for JSON Schema Draft-07
Fluent interface for intuitive schema building
Support for all schema types:
- object, array, string, number, integer, boolean, null
- enum, const, ref, if/then/else, not, allOf, anyOf, oneOf
Schema composition and nesting
JSON serialization via toArray() or json_encode()

Installation

Composer

composer require asokol1981/json-schema-php

VCS

If the package is not available on Packagist, you can install it by adding the following to your composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/asokol1981/json-schema-php"
    }
  ],
  "require": {
    "asokol1981/json-schema-php": "dev-main"
  }
}

Then run:

composer update

⚠️ Make sure your project allows the dev-main version or use a specific tag (e.g. ^1.0) once available.

Usage

use ASokol1981\JsonSchema\Draft07\ObjectSchema;
use ASokol1981\JsonSchema\Draft07\StringSchema;
use ASokol1981\JsonSchema\Draft07\IntegerSchema;

$schema = (new ObjectSchema([
    'name' => (new StringSchema())->minLength(1),
    'age' => (new IntegerSchema())->minimum(0)
]))->setRequired('name');

echo json_encode($schema, JSON_PRETTY_PRINT);

Output:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "age": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["name"]
}

Directory Structure

Schemas are organized under the ASokol1981\JsonSchema\Draft07 namespace, including:

StringSchema
ObjectSchema
ArraySchema
AllOfSchema, AnyOfSchema, NotSchema, RefSchema, etc.

🛠️ Makefile Commands

To simplify local development, the following make commands are available:

📦 Installation

make install

Builds the Docker container, starts it in the background, and installs Composer dependencies.

🏗️ Build Image

make build

Builds the Docker image with the tag asokol1981/json-schema-php.

▶️ Start Container

make start

Starts the container in detached mode.

⏹️ Stop Container

make stop

Stops and removes the container (volumes are preserved).

🧹 Uninstall

make uninstall

Stops and removes the container, associated volumes, and the Docker image.

🐚 Shell Access

make exec -- bash

Runs a command inside the container. Be sure to use -- to separate make arguments from the actual command:

make exec -- php -v

🎼 Composer

make composer -- require --dev phpunit/phpunit

Executes a Composer command inside the container. Example: install PHPUnit as a dev dependency.

✅ Run Tests

make test

Runs tests and shows code coverage summary in the terminal.

📊 HTML Coverage Report

make coverage

Generates a code coverage report in HTML format and saves it in the coverage/ directory.

🧱 Artisan

make artisan -- list

Executes an Artisan command inside the container.

🧹 Code Style Fix

make php-cs-fixer

Runs PHP-CS-Fixer inside the container to automatically fix coding style issues according to the defined .php-cs-fixer.dist.php configuration.

✅ Validate Codecov Configuration

You can validate codecov.yml configuration using:

make codecov-validate

This command checks the syntax and structure of the codecov.yml file using Codecov’s validation API. It helps catch errors before pushing changes.

ℹ️ Note: When passing arguments to exec, composer, artisan, test, or coverage targets, always prefix them with -- so make doesn't interpret them as its own flags.

Roadmap

Support for newer drafts (e.g. 2020-12)

asokol1981 / json-schema-php

Maintainers

Details