Opis JSON Schema

Opis JSON Schema is a PHP implementation of the JSON Schema standard. It supports multiple drafts including draft-2020-12, draft-2019-09, draft-07, and draft-06.

Key capabilities include:

• Customization: Use the $error keyword for custom errors, $filters for custom PHP filters, and custom formats or media types.
• Advanced Schema Logic: Support for the $map keyword for schema reuse, slots for schema composition, and the $data keyword.
• Navigation & Data: Support for absolute and relative json pointers, URI templates, and casting via pragmas.

You can install Opis JSON Schema using the Composer command line interface or by manually adding it to your composer.json file. This library is used to validate JSON documents against various JSON Schema drafts (from draft-06 to draft-2020-12).

composer require opis/json-schema

To add Opis JSON Schema as a direct dependency in your composer.json file, add the following entry to your require block:

{
    "require": {
        "opis/json-schema": "^2.6"
    }
}

The ValidationContext class is a stateful object used during the JSON Schema validation process. It tracks the current data being validated, the path within the JSON document, global variables, and configuration settings like error limits.

While typically managed internally by the library, understanding its methods is useful for debugging or extending the validation logic. It provides methods to navigate the data tree using pushDataPath() and popDataPath(), and to access the current data via currentData() and currentDataType().

The FilterResolver supports namespacing to prevent collisions and organize filters. By default, the separator is ::.

When resolving or registering a filter, you can include the namespace in the name string. If the separator is not present, the resolver falls back to the defaultNS.

You can also register entire FilterResolver instances as namespaces using registerNS() to create a hierarchical resolution structure.

// Registering a namespaced filter
$resolver->registerCallable('string', 'custom::my-filter', $myCallable);

// Registering a whole namespace of resolvers
$subResolver = new FilterResolver();
$resolver->registerNS('custom', $subResolver);

The SchemaResolver class is responsible for locating and loading JSON schema definitions based on URIs. It supports several methods for defining how schemas are found:

1. Raw Schemas: Registering schema objects or JSON strings directly in memory.
2. File Mapping: Mapping specific schema IDs to local file paths.
3. Protocols: Registering custom handlers (callables) for specific URI schemes (e.g., https, file).
4. Prefixes: Mapping URI prefixes to specific directories for path-based resolution.
5. Protocol Directories: Mapping a combination of scheme and host to a base directory.

When resolve(Uri $uri) is called, the resolver checks protocols first, then raw registered schemas, and finally attempts to resolve a file path via registered files, protocol directories, or prefixes.

Before installing, ensure your environment meets the following PHP version requirements:

• PHP ^7.4 || ^8.0

The ValidationContext maintains a pointer to the current position in the JSON document. You can traverse the document structure using the following methods:

• pushDataPath($key): Moves the context deeper into the document by a specific key or index. This updates both the currentDataPath() and the fullDataPath().
• popDataPath(): Moves the context back up one level in the document hierarchy.
• currentDataPath(): Returns an array of keys/indices representing the path from the root to the current element.
• fullDataPath(): Returns the complete path to the current element.

Once formats are registered, you can retrieve the validation logic using the resolve or resolveAll methods.

Resolve a specific format

Use resolve(string $name, string $type) to find the validator for a specific format name within a specific JSON type. It returns a Format object, a callable, or null if no match is found.

Resolve all formats with a specific name

Use resolveAll(string $name) to find all validators across all types that share the same format name. This returns an array of validators indexed by type, or null if none exist.

// Get a specific validator
$validator = $resolver->resolve('email', 'string');
if ($validator !== null) {
    // $validator is a Format or callable
}

// Get all validators named 'uri' across different types
$allUriValidators = $resolver->resolveAll('uri');

To retrieve a filter for validation, use the resolve() method. It takes the filter name (optionally namespaced) and the JSON type.

• resolve(string $name, string $type): Returns the Filter, callable, or null if not found.
• resolveAll(string $name): Returns an array of all filters associated with a specific name (across all types) or null if the name/namespace does not exist.