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.
PHP 8.2 or newer.
composer require phpnomad/json-schemaYou will also need a concrete implementation package. The canonical one is phpnomad/opis-json-schema-integration.
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.
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;
}Thrown on validation failure. Exposes a readonly collection of ValidationFailure.
final class ValidationError extends \Exception
{
/** @var ValidationFailure[] */
public readonly array $failures;
}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.
}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.