README

Concrete JsonSchemaValidatorStrategy implementation backed by opis/json-schema. Drop in to satisfy phpnomad/json-schema with full draft 2020-12 support.

Requirements

PHP 8.2 or newer.

Installation

composer require phpnomad/opis-json-schema-integration

This pulls in both phpnomad/json-schema (the abstraction) and opis/json-schema (the concrete validator) automatically.

Usage

use PHPNomad\JsonSchema\Exceptions\ValidationError;
use PHPNomad\OpisJsonSchema\Integration\Strategies\OpisJsonSchemaValidator;

$validator = new OpisJsonSchemaValidator();

try {
    $validator->validate(
        ['name' => 'Alice', 'age' => 30],
        '/path/to/person.schema.json',
    );
} catch (ValidationError $e) {
    foreach ($e->failures as $failure) {
        printf(
            "%s: %s [%s]\n",
            $failure->path,
            $failure->message,
            $failure->keyword,
        );
    }
}

Schema resolution

The $schemaUri argument accepts:

• A local file path — the file is read and parsed as JSON before validation.
• A URI string — passed straight through to Opis's resolver. Register prefixes or IDs on the underlying Opis\JsonSchema\Validator beforehand if you need custom resolution.

Custom Opis configuration

Subclass OpisJsonSchemaValidator and override the protected buildValidator() method to customize keyword registration, resolver prefixes, or other Opis behavior:

use Opis\JsonSchema\Validator as OpisValidator;
use PHPNomad\OpisJsonSchema\Integration\Strategies\OpisJsonSchemaValidator;

final class MySiteJsonSchemaValidator extends OpisJsonSchemaValidator
{
    protected function buildValidator(): OpisValidator
    {
        $validator = parent::buildValidator();
        $validator->resolver()->registerPrefix('https://my-site.example/', '/path/to/schemas');

        return $validator;
    }
}

The no-arg constructor keeps the class safe to auto-wire through standard dependency injection containers.

How failures are reported

Every Opis leaf error becomes a PHPNomad\JsonSchema\ValidationFailure:

• path — data pointer, dotted notation (e.g. programs.gold.incentiveType; empty string at the root).
• message — Opis's error message with placeholder substitution applied.
• keyword — the JSON Schema keyword that failed (required, type, enum, etc.).

Container errors (allOf, oneOf, anyOf) are unwrapped — only the leaf violations are surfaced, so callers see one entry per actual problem.

License

MIT