phpnomad/json-schema

Platform-agnostic JSON Schema validation contract for PHPNomad. Ships interfaces only — pair with a concrete integration package (e.g. opis-json-schema-integration).

1.0.0 2026-04-19 19:12 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• Alex Standiford

• abstraction
• validation
• interface
• json-schema
• phpnomad

README

Platform-agnostic JSON Schema validation contract for PHPNomad. Your code depends on a small interface; the concrete validator implementation is swappable without touching consumers.

This package ships interfaces only. Pair it with an implementation package — for example, a wrapper around opis/json-schema, or roll your own against any library that exposes per-violation metadata.

Requirements

PHP 8.2 or newer.

Installation

composer require phpnomad/json-schema

You will also need a concrete implementation package. The canonical one is phpnomad/opis-json-schema-integration.

Usage

use PHPNomad\JsonSchema\Interfaces\JsonSchemaValidatorStrategy;
use PHPNomad\JsonSchema\Exceptions\ValidationError;

/** @var JsonSchemaValidatorStrategy $validator */
try {
    $validator->validate($data, '/path/to/schema.json');
    // Validation passed.
} catch (ValidationError $e) {
    foreach ($e->failures as $failure) {
        // $failure->path, $failure->message, $failure->keyword
    }
}

validate() returns true on success and throws ValidationError on failure. The exception carries the full collection of failures — one entry per violation — so callers can report every problem in a single pass rather than a fail-fast single message.

Contract

JsonSchemaValidatorStrategy

The single validation entry point. Implementations resolve $schemaUri (a file path, URL, or registered schema identifier) to a JSON Schema document and validate $data against it.

interface JsonSchemaValidatorStrategy
{
    /**
     * @throws ValidationError When validation fails.
     */
    public function validate(array $data, string $schemaUri): bool;
}

ValidationError

Thrown on validation failure. Exposes a readonly collection of ValidationFailure.

final class ValidationError extends \Exception
{
    /** @var ValidationFailure[] */
    public readonly array $failures;
}

ValidationFailure

A single violation. All fields are readonly promoted properties.

final class ValidationFailure
{
    public readonly string $path;     // pointer to the offending location, e.g. "programs.gold.incentiveType"
    public readonly string $message;  // human-readable description
    public readonly string $keyword;  // JSON Schema keyword that failed — "type", "required", "enum", etc.
}

Why an abstraction

Recipe importers, configuration validators, and schema-driven APIs are natural places to want JSON Schema validation, but picking a specific library locks that choice into every consumer. This package lets your code depend on the idea of validating against a JSON Schema without caring which library actually does the work — swap implementations for performance, draft support, or licensing reasons without touching downstream code.

License

MIT