Opis JSON Schema

https://github.com/opis/json-schema
Admin
A PHP implementation of the JSON Schema standard (draft-2020-12, draft-2019-09, draft-07, draft-06)...
Tokens:165,941
Snippets:1,148
Trust Score:8.7
License:Apache-2.0
Update:3 days ago
Show doc for...
Tokens:
Raw
### Full custom configuration example

Source: https://github.com/opis/json-schema

Shows how to configure a custom SchemaResolver, SchemaParser, and Validator with custom options. This example registers a file protocol, disables filters, sets the default draft, and configures content decoding.

```APIDOC
## Full custom configuration example

### Description
Demonstrates a complete custom configuration for the Opis JSON Schema validator.

### Code
```php
use Opis\JsonSchema\{Validator, SchemaLoader};
use Opis\JsonSchema\Parsers\SchemaParser;
use Opis\JsonSchema\Resolvers\{SchemaResolver, FormatResolver};

$resolver = new SchemaResolver();
$resolver->registerProtocol('file', fn($uri) => file_get_contents($uri->path()));

$parser = new SchemaParser(
    ['format' => new FormatResolver()],
    [
        'allowFilters' => false,
        'defaultDraft' => '2020-12',
        'decodeContent' => ['06', '07', '2019-09'],
    ]
);

$validator = new Validator(new SchemaLoader($parser, $resolver), max_errors: 10, stop_at_first_error: false);
```
```

--------------------------------

### Install opis/json-schema with composer require

Source: https://github.com/opis/json-schema/blob/master/README.md

Install the package from the command line using Composer. Requires PHP ^7.4 or ^8.0.

```bash
composer require opis/json-schema
```

--------------------------------

### TracePragma (custom pragma example)

Source: https://github.com/opis/json-schema

Example of a custom pragma implementation that logs entry and exit. This is a user-defined class that implements the Pragma interface.

```APIDOC
## TracePragma (custom pragma example)

### Description
Example of a custom pragma that logs entry and exit. This is a user-defined class that implements the Pragma interface.

### Methods
- `enter(ValidationContext $context)` - Logs "enter: {label}" and returns null.
- `leave(ValidationContext $context, $data): void` - Logs "leave: {label}".

### Request Example
```php
use Opis\JsonSchema\{Pragma, ValidationContext};

final class TracePragma implements Pragma
{
    public function __construct(private string $label) {}

    public function enter(ValidationContext $context)
    {
        error_log("enter: {$this->label}");
        return null;
    }

    public function leave(ValidationContext $context, $data): void
    {
        error_log("leave: {$this->label}");
    }
}
```
```

--------------------------------

### SchemaResolver usage example

Source: https://github.com/opis/json-schema

Shows how to register raw schemas, file mappings, custom protocols, and directory mappings for a host.

```php
use Opis\JsonSchema\Resolvers\SchemaResolver;

$resolver = new SchemaResolver();

// 1. raw schema
$resolver->registerRaw((object) ['type' => 'number'], 'https://example.com/number');

// 2. file mapping
$resolver->registerFile('https://example.com/product', '/schemas/product.json');

// 3. custom protocol
$resolver->registerProtocol('db', fn($uri) => $pdo->query('SELECT schema FROM t WHERE id = :id', $uri->path()));

// 4. directory mapping for a host
$resolver->registerProtocolDir('https', 'example.com', __DIR__ . '/schemas');
```

--------------------------------

### Schema-level pragma usage example

Source: https://github.com/opis/json-schema

Shows how to use pragmas at the schema level via the $pragma keyword. The example sets cast to 'object', maxErrors to 10, globals with a currency variable, and slots with a header schema. This is the typical way pragmas are applied in a JSON Schema.

```json
{
  "type": "object",
  "$pragma": {
    "cast": "object",
    "maxErrors": 10,
    "globals": { "currency": "USD" },
    "slots": { "header": { "type": "string" } }
  },
  "properties": {
    "price": { "type": "number" }
  }
}
```

--------------------------------

### Schema usage with format email

Source: https://github.com/opis/json-schema

JSON Schema example showing the 'email' format applied to a string type.

```json
{
  "type": "string",
  "format": "email"
}
```

--------------------------------

### Walking compiled schemas example

Source: https://github.com/opis/json-schema

Shows how to parse schemas and check their types. Uses SchemaInfo with object type and boolean false; demonstrates accessing draft and idBaseRoot, and that BooleanSchema validate always fails for false.

```php
use Opis\JsonSchema\Validator;
use Opis\JsonSchema\Schemas\{ObjectSchema, BooleanSchema, EmptySchema};

$validator = new Validator();
$schema = $validator->parser()->parseSchema(
    new \Opis\JsonSchema\Info\SchemaInfo((object) ['type' => 'object'], null)
);

if ($schema instanceof ObjectSchema) {
    $info = $schema->info();
    echo $info->draft();        // "2020-12" (default)
    echo $info->idBaseRoot();   // Uri|null
}

$bool = $validator->parser()->parseSchema(new \Opis\JsonSchema\Info\SchemaInfo(false, null));
if ($bool instanceof BooleanSchema) {
    // $bool->validate($context) always fails
}
```

--------------------------------

### Parsing and fragment handling example

Source: https://github.com/opis/json-schema

Shows how to parse a URI with a fragment and access its components. The ensure_fragment parameter adds '#' so fragment() returns an empty string instead of null.

```php
use Opis\JsonSchema\Uri;

$uri = Uri::parse('https://example.com/schemas/user.json#/properties/name', true);
echo $uri->scheme();        // "https"
echo $uri->host();          // "example.com"
echo $uri->fragment();      // "/properties/name"
echo $uri->isAbsolute();    // true
$json = json_encode($uri);  // "https://example.com/schemas/user.json#/properties/name"

// ensure_fragment adds '#' so fragment() returns '' instead of null
$empty = Uri::parse('https://example.com/x', true);
echo $empty->fragment();    // ""
```

--------------------------------

### Examples

Source: https://github.com/opis/json-schema

Basic validation with an inline schema object and error handling with raw error access.

```APIDOC
## Examples

### Description
Basic validation with an inline schema object and error handling with raw error access.

### Method
PHP code examples

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
None

### Request Example
```php
use Opis\JsonSchema\Validator;

$validator = new Validator();

$data = (object) ['name' => 'John Doe', 'age' => 30];
$schema = (object) [
    'type' => 'object',
    'properties' => (object) [
        'name' => (object) ['type' => 'string'],
        'age' => (object) ['type' => 'integer', 'minimum' => 18],
    ],
    'required' => ['name'],
];

$result = $validator->validate($data, $schema);

if ($result->isValid()) {
    echo 'Data is valid';
} else {
    echo $result->error()->message();      // e.g. "Number must be greater than or equal to 18"
    echo $result->error()->keyword();      // "minimum"
}
```

### Request Example
```php
use Opis\JsonSchema\Validator;
use Opis\JsonSchema\Exceptions\SchemaException;

$validator = new Validator();
$validator->setMaxErrors(5);

try {
    $error = $validator->dataValidation('not-an-object', '{"type":"object","required":["id"]}');
    if ($error !== null) {
        printf('Validation failed at %s for keyword %s: %s',
            $error->data()->fullPath()[0] ?? '/',
            $error->keyword(),
            $error->message()
        );
        foreach ($error->subErrors() as $sub) {
            echo $sub->message();
        }
    }
} catch (SchemaException $e) {
    // Schema itself could not be parsed (e.g. malformed keyword value)
    echo $e->getMessage();
}
```
```

--------------------------------

### Using $filters with regex and data-exists

Source: https://github.com/opis/json-schema

Shows how to use the $filters keyword with built-in filters 'regex' and 'data-exists'. The first example validates a string against a regex pattern; the second checks if a data path exists in the root, using the 'anything' global option.

```php
use Opis\JsonSchema\Validator;

$validator = new Validator();

// $filters receiving globals and args
$result = $validator->validate(
    'widget-1',
    (object) ['$filters' => (object) [
        'regex' => (object) ['pattern' => '^widget-\d+$'],
    ]]
);
// $result->isValid() === true

// data-exists against the root
$result = $validator->validate(
    (object) ['a' => 1],
    (object) ['$filters' => (object) [
        'data-exists' => (object) ['ref' => '#/a'],
    ]],
    ['anything' => true]   // $globals
);
```

--------------------------------

### ContentEncodingResolver usage example

Source: https://github.com/opis/json-schema

Creates a resolver, registers a custom 'gzip' callable, and calls the static DecodeBase64 method. The static method returns 'hello' for the given input.

```php
use Opis\JsonSchema\Resolvers\ContentEncodingResolver;

$enc = new ContentEncodingResolver();
$enc->registerCallable('gzip', fn($v) => gzdecode($v) ?: null);
$out = \Opis\JsonSchema\Resolvers\ContentEncodingResolver::DecodeBase64('aGVsbG8='); // "hello"
```

--------------------------------

### Inspect keyword error details with ValidationError

Source: https://github.com/opis/json-schema

Shows how to run a data validation and inspect the returned ValidationError. The example validates the number 5 against a minimum of 10 and maximum of 20, then prints the failing keyword, its arguments, and a token-substituted message. The output shows keyword "minimum", args min 10, and message "Number must be greater than or equal to 10".

```php
use Opis\JsonSchema\Validator;
use Opis\JsonSchema\Errors\ValidationError;

$validator = new Validator();
$error = $validator->dataValidation(5, (object) ['minimum' => 10, 'maximum' => 20]);

if ($error) {
    echo $error->keyword();          // "minimum"
    echo $error->args()['min'];      // 10
    echo $error->message();          // "Number must be greater than or equal to 10" (token-substituted)
}
```

--------------------------------

### FormatResolver usage example

Source: https://github.com/opis/json-schema

Shows how to instantiate FormatResolver, register a callable format for the 'slug' name on the 'string' type, and resolve it. The callable uses a regular expression to validate slug format.

```php
use Opis\JsonSchema\Resolvers\FormatResolver;

$formats = new FormatResolver();
$formats->registerCallable('string', 'slug', fn(string $value): bool =>
    (bool) preg_match('/^[a-z0-9]+(-[a-z0-9]+)*$/', $value)
);
$handler = $formats->resolve('slug', 'string'); // callable
```

--------------------------------

### Strict validation example using CompliantValidator

Source: https://github.com/opis/json-schema

Shows how to use CompliantValidator for strict validation. The example validates an integer against a schema and outputs true, demonstrating that extension filters are not available.

```php
use Opis\JsonSchema\CompliantValidator;
use Opis\JsonSchema\Filters\CommonFilters; // extension filter would not be available

$validator = new CompliantValidator();
$result = $validator->validate(123, (object) ['type' => 'integer']);
var_dump($result->isValid()); // true
```

--------------------------------

### Merging references against a base example

Source: https://github.com/opis/json-schema

Demonstrates resolving relative and absolute references against a base URI. Absolute references win, relative paths are resolved against the base, and fragment-only references are appended to the base.

```php
use Opis\JsonSchema\Uri;

$base = Uri::parse('https://example.com/schemas/root.json', true);

$abs = Uri::merge('https://other.org/s.json', $base, true);   // absolute wins
echo $abs;                                                    // https://other.org/s.json#

$rel = Uri::merge('./child.json', $base, true);
echo $rel;                                                    // https://example.com/schemas/child.json#

$frag = Uri::merge('#/definitions/x', $base, true);
echo $frag;                                                   // https://example.com/schemas/root.json#/definitions/x
```

--------------------------------

### Override or remove built-in formats

Source: https://github.com/opis/json-schema

PHP example showing how to replace the built-in 'email' format with a custom class and remove the 'uuid' format using FormatResolver methods.

```php
$formats->register('string', 'email', new MyStrictEmailFormat()); // replace
$formats->unregister('string', 'uuid');                           // remove
```

--------------------------------

### Using RefVariablesContainer directly

Source: https://github.com/opis/json-schema

Demonstrates constructing RefVariablesContainer directly with a parsed JsonPointer, an optional default, and an optional $each template. Shows resolve() output and hasDefaultValue() behavior. The second example maps each element of a list through a nested $each template.

```php
use Opis\JsonSchema\JsonPointer;
use Opis\JsonSchema\Variables\RefVariablesContainer;

$ref = new RefVariablesContainer(JsonPointer::parse('#/config'), null, ['default' => 'x']);
$v = $ref->resolve((object) ['config' => 'auto']);
echo $v;                       // "auto"
echo $ref->hasDefaultValue();  // true

$each = new RefVariablesContainer(JsonPointer::parse('#/list'), new VariablesContainer(
    (object) ['$ref' => '#/names/$each']
));
var_export($each->resolve((object) ['list' => [1, 2]])); // [1, 2] mapped through $each
```

--------------------------------

### FilterResolver usage example

Source: https://github.com/opis/json-schema

Demonstrates registering a callable filter for the 'slug' name on the 'string' type, then reusing a shared resolver under the 'utils' namespace. The schema can then use "$filters": {"utils::slug": {...}}.

```php
use Opis\JsonSchema\Resolvers\FilterResolver;
use Opis\JsonSchema\Filters\CommonFilters;

$filters = new FilterResolver();
$filters->registerCallable('string', 'slug', function ($value, array $args): bool {
    return isset($args['pattern']) && (bool) preg_match($args['pattern'], $value);
});

// namespace reuse: ship a shared resolver under the 'utils' namespace
$shared = new FilterResolver();
$shared->registerCallable('string', 'slug', $filters->resolve('slug', 'string'));
$filters->registerNS('utils', $shared);
// schema can now use "$filters": {"utils::slug": {...}}
```

--------------------------------

### Registering a custom filter programmatically

Source: https://github.com/opis/json-schema

Registers a custom filter 'slug' for the 'string' type using FilterResolver, then uses it in a schema. The filter checks a regex pattern against the value. The example shows the full setup with SchemaParser and SchemaLoader.

```php
use Opis\JsonSchema\Resolvers\FilterResolver;
use Opis\JsonSchema\Parsers\SchemaParser;
use Opis\JsonSchema\Validator;

$filters = new FilterResolver();
$filters->registerCallable('string', 'slug', function (string $value, array $args): bool {
    return isset($args['pattern']) && (bool) preg_match($args['pattern'], $value);
});

$parser = new SchemaParser(['$filters' => $filters]);
$validator = new Validator(new \Opis\JsonSchema\SchemaLoader($parser));

$result = $validator->validate('hello-world', (object) [
    '$filters' => (object) [
        'slug' => (object) ['pattern' => '/^[a-z-]+$/'],
    ],
]);
var_dump($result->isValid());  // true
```

--------------------------------

### getOptions

Source: https://github.com/opis/json-schema

Returns all configured options as an array.

```APIDOC
## getOptions

### Description
Returns all configured options as an array.

### Method
getOptions

### Signature
```php
public function getOptions(): array
```

### Return Value
array - The array of all configured options.
```

--------------------------------

### SchemaParser constructor

Source: https://github.com/opis/json-schema

Creates a SchemaParser instance. Custom vocabularies can be passed as `$extraVocabulary`.

```APIDOC
## SchemaParser::__construct()

### Description
Creates a SchemaParser instance.

### Method
`new SchemaParser($extraVocabulary = [])`

### Parameters
- **$extraVocabulary** (array) - Optional - Custom vocabularies to register.
```

--------------------------------

### ContentMediaTypeResolver constructor

Source: https://github.com/opis/json-schema

Creates a ContentMediaTypeResolver with optional media list and default media.

```APIDOC
## ContentMediaTypeResolver::__construct()

### Description
Creates a ContentMediaTypeResolver instance.

### Method
`new ContentMediaTypeResolver(array $media = [], $defaultMedia = null)`

### Parameters
- **$media** (array) - Optional - List of media types, defaults to empty.
- **$defaultMedia** (mixed) - Optional - Default media type, defaults to null.
```

--------------------------------

### Building a custom pragma with TracePragma

Source: https://github.com/opis/json-schema

Shows how to build a custom pragma by implementing the Pragma interface. The TracePragma logs enter and leave events with a label. Register it via Vocabulary::appendPragma() and PragmaKeywordValidatorParser will pick it up.

```php
use Opis\JsonSchema\{Pragma, ValidationContext};

final class TracePragma implements Pragma
{
    public function __construct(private string $label) {}

    public function enter(ValidationContext $context)
    {
        error_log("enter: {$this->label}");
        return null;
    }

    public function leave(ValidationContext $context, $data): void
    {
        error_log("leave: {$this->label}");
    }
}
```

--------------------------------

### baseUri() and setBaseUri() methods

Source: https://github.com/opis/json-schema

Gets or sets the base URI used to absolutize relative URIs passed to loadSchemaById(). Defaults to null.

```php
public function baseUri(): ?Uri
public function setBaseUri(?Uri $uri): self
```

--------------------------------

### Constructor

Source: https://github.com/opis/json-schema

Creates a new SchemaLoader instance with optional parser, resolver, and JSON string decoding settings.

```APIDOC
## Constructor

### Description
Creates a new SchemaLoader instance with optional parser, resolver, and JSON string decoding settings.

### Method
Constructor

### Signature
`public function __construct(?SchemaParser $parser = null, ?SchemaResolver $resolver = null, bool $decodeJsonString = true)`

### Parameters
- `$parser` (?SchemaParser) - Optional - When null, a new SchemaParser is created.
- `$resolver` (?SchemaResolver) - Optional - When null, URI lookups not in cache return null.
- `$decodeJsonString` (bool) - Optional - When true, JSON strings from resolver are decoded before use.
```

--------------------------------

### Constructor

Source: https://github.com/opis/json-schema

Creates a new SchemaParser instance with optional resolvers, options, and extra vocabulary.

```APIDOC
## Constructor

### Description
Creates a new SchemaParser instance with optional resolvers, options, and extra vocabulary.

### Method
Constructor

### Signature
```php
public function __construct(
    array $resolvers = [],
    array $options = [],
    ?Vocabulary $extraVocabulary = null
)
```

### Parameters
- `$resolvers` (array) - Optional - Keys `format`, `contentEncoding`, `contentMediaType`, `$filters`; missing keys receive default resolver instances.
- `$options` (array) - Optional - Overrides for `DEFAULT_OPTIONS`.
- `$extraVocabulary` (?Vocabulary) - Optional - Keyword-validator/pragma parsers merged into every draft; defaults to `new DefaultVocabulary()`.
```

--------------------------------

### valueIsOfJsonType($value, $type): bool

Source: https://github.com/opis/json-schema

Determines if a value is of a given JSON type by first getting its JSON type and then checking if it matches.

```APIDOC
## valueIsOfJsonType($value, $type): bool

### Description
Determines if a value is of a given JSON type by first getting its JSON type and then checking if it matches.

### Method
valueIsOfJsonType

### Parameters
- **$value** (mixed) - Required - The value to check.
- **$type** (string) - Required - The JSON type to check against.

### Return Value
- **bool** - True if the value is of the given type, false otherwise.
```

--------------------------------

### Using ValidationResult with Validator::validate()

Source: https://github.com/opis/json-schema

Shows how to validate data and check the result. The example validates the string 'abc' against a number type, which fails, and prints the error message.

```php
use Opis\JsonSchema\Validator;

$result = (new Validator())->validate('abc', (object) ['type' => 'number']);
if ($result->hasError()) {
    echo (string) $result; // e.g. "The data ({type}) must match the type: {expected}"
}
```

--------------------------------

### Option access methods

Source: https://github.com/opis/json-schema

option() returns the configured value or the provided default (null if not given). setOption() is fluent and returns self.

```php
public function option(string $name, $default = null)   // mixed|null
public function setOption(string $name, $value): self
public function getOptions(): array
```

--------------------------------

### SchemaInfo::__construct

Source: https://github.com/opis/json-schema

Creates a new SchemaInfo instance with the given schema data and URI context. This constructor is part of the public API for the SchemaInfo class.

```APIDOC
## SchemaInfo::__construct

### Description
Creates a new SchemaInfo instance with the given schema data and URI context.

### Method
Constructor

### Signature
```php
public function __construct(
    $data,
    ?Uri $id,
    ?Uri $base = null,
    ?Uri $root = null,
    array $path = [],
    ?string $draft = null
)
```

### Parameters
- **$data** (bool|object) - Required - Raw schema data.
- **$id** (?Uri) - Required - Schema's own id (from `$id` or `$anchor`).
- **$base** (?Uri) - Optional - Base URI for resolving relative references (nearest enclosing id).
- **$root** (?Uri) - Optional - Document root id. If `$root === $id` (string-equal), `$root` is set to `null`; if `$root` is `null`, `$base` is also forced to `null`.
- **$path** (array) - Optional - Path of this subschema within the document (used for pointer-based error locations).
- **$draft** (?string) - Optional - Draft version string.
```

--------------------------------

### getJsonSuperType(string $type): ?string

Source: https://github.com/opis/json-schema

Returns the super type from JSON_SUBTYPES for the given type, or null if not found. For example, 'integer' returns 'number'.

```APIDOC
## getJsonSuperType(string $type): ?string

### Description
Returns the super type from JSON_SUBTYPES for the given type, or null if not found. For example, 'integer' returns 'number'.

### Method
getJsonSuperType

### Parameters
- **$type** (string) - Required - The type to get the super type for.

### Return Value
- **?string** - The super type or null.
```

--------------------------------

### Register custom format hex-color

Source: https://github.com/opis/json-schema

PHP example registering a custom 'hex-color' format via FormatResolver::registerCallable. The format uses a regex to match hex color strings; validation of '#ff0000' returns true.

```php
use Opis\JsonSchema\Resolvers\FormatResolver;
use Opis\JsonSchema\Parsers\SchemaParser;
use Opis\JsonSchema\Validator;

$formats = new FormatResolver();
$formats->registerCallable('string', 'hex-color', fn(string $v): bool =>
    (bool) preg_match('/^#[0-9a-f]{6}$/i', $v)
);

$parser = new SchemaParser(['format' => $formats]);
$validator = new Validator(new \Opis\JsonSchema\SchemaLoader($parser));

$result = $validator->validate('#ff0000', (object) ['format' => 'hex-color']);
var_dump($result->isValid());            // true
```

--------------------------------

### SchemaParser::__construct

Source: https://github.com/opis/json-schema

Constructor for the SchemaParser class. Configures resolvers, options, and extra vocabulary.

```APIDOC
## SchemaParser::__construct

### Description
Constructor for the SchemaParser class. Configures resolvers, options, and extra vocabulary.

### Method
Constructor

### Signature
```php
public function __construct(
    array $resolvers = [],
    array $options = [],
    ?Vocabulary $extraVocabulary = null
)
```

### Parameters
- **$resolvers** (array) - Optional - Resolver map. Keys: `format`, `contentEncoding`, `contentMediaType`, `$filters`. Missing keys are auto-filled with default resolvers. Values may be `null` to disable.
- **$options** (array) - Optional - Overrides for the defaults below.
- **$extraVocabulary** (?Vocabulary) - Optional - Custom keywords/validators/pragmas appended to every draft.
```

--------------------------------

### create($sender, $mapper, $globals, $slots, $maxErrors, $stop_at_first_error)

Source: https://github.com/opis/json-schema

Like `newInstance()` but allows a `$mapper` (resolved against root data + current path to produce the new context's data) and a `$globals` resolver (merged over inherited globals). Used by `$ref` implementation.

```APIDOC
## create

### Description
Like `newInstance()` but allows a `$mapper` (resolved against root data + current path to produce the new context's data) and a `$globals` resolver (merged over inherited globals). Used by `$ref` implementation.

### Method
create

### Signature
```php
public function create(
    Schema $sender,
    ?Variables $mapper = null,
    ?Variables $globals = null,
    ?array $slots = null,
    ?int $maxErrors = null,
    ?bool $stop_at_first_error = null
): self
```

### Parameters
- **$sender** (Schema) - Required - Schema that created the context.
- **$mapper** (?Variables) - Optional - Resolved against root data + current path to produce the new context's data.
- **$globals** (?Variables) - Optional - Resolver merged over inherited globals.
- **$slots** (?array) - Optional - Slot definitions.
- **$maxErrors** (?int) - Optional - Error budget.
- **$stop_at_first_error** (?bool) - Optional - Early-stop flag.

### Returns
- **self** - The new ValidationContext instance.
```

--------------------------------

### Helper::getJsonSuperType(string $type): ?string

Source: https://github.com/opis/json-schema

Returns the super type for a given JSON subtype. For example, 'integer' maps to 'number'. Returns null if the type is not recognized.

```APIDOC
## Helper::getJsonSuperType

### Description
Returns the super type for a given JSON subtype.

### Method
`getJsonSuperType`

### Signature
```php
public static function getJsonSuperType(string $type): ?string
```

### Parameters
- **$type** (string) - Required - The JSON type or subtype.

### Return Value
- **?string** - The super type, or `null` if not recognized.
```

--------------------------------

### Programmatic pragma construction with CastPragma

Source: https://github.com/opis/json-schema

Shows rare programmatic construction of a pragma, normally created by parsers. Creates a CastPragma for 'integer', enters it on a context with data '42', prints the casted integer, then leaves to restore. Also demonstrates toBoolean('') returning false and toArray(5) returning [5].

```php
use Opis\JsonSchema\Pragmas\CastPragma;
use Opis\JsonSchema\ValidationContext;

$cast = new CastPragma('integer');
$context = $validator->createContext('42');
$old = $cast->enter($context);
echo $context->currentData();      // 42 (int)
$cast->leave($context, $old);      // restore "42"

echo $cast->toBoolean('');         // false
echo $cast->toArray(5);            // [5]
```

--------------------------------

### ContentEncodingResolver constructor

Source: https://github.com/opis/json-schema

Creates a ContentEncodingResolver with optional list and default encoding.

```APIDOC
## ContentEncodingResolver::__construct()

### Description
Creates a ContentEncodingResolver instance.

### Method
`new ContentEncodingResolver(array $list = [], $defaultEncoding = null)`

### Parameters
- **$list** (array) - Optional - List of encodings, defaults to empty.
- **$defaultEncoding** (mixed) - Optional - Default encoding, defaults to null.
```

--------------------------------

### Validate email format with Opis Validator

Source: https://github.com/opis/json-schema

PHP example using Opis\JsonSchema\Validator to validate an email address. The first validation returns true; the second fails with keyword 'format' and message "The data must match the 'email' format".

```php
use Opis\JsonSchema\Validator;
use Opis\JsonSchema\Resolvers\FormatResolver;

$validator = new Validator();

$result = $validator->validate('user@example.com', (object) ['format' => 'email']);
var_dump($result->isValid());            // true

$result = $validator->validate('not-an-email', (object) ['format' => 'email']);
if ($result->hasError()) {
    echo $result->error()->keyword();    // "format"
    echo $result->error()->message();    // "The data must match the 'email' format"
}
```

--------------------------------

### Vocabulary::__construct

Source: https://github.com/opis/json-schema

Creates a new Vocabulary instance, optionally pre-populating it with keyword parsers, keyword validator parsers, and pragma parsers. All mutators are fluent.

```APIDOC
## Vocabulary::__construct

### Description
Creates a new Vocabulary instance, optionally pre-populating it with keyword parsers, keyword validator parsers, and pragma parsers.

### Method
`__construct`

### Signature
```php
public function __construct(array $keywords = [], array $keywordValidators = [], array $pragmas = [])
```

### Parameters
- **$keywords** (array) - Optional - Array of KeywordParser instances.
- **$keywordValidators** (array) - Optional - Array of KeywordValidatorParser instances.
- **$pragmas** (array) - Optional - Array of PragmaParser instances.

### Returns
No return value (constructor).
```

--------------------------------

### SchemaParser constructor

Source: https://github.com/opis/json-schema

Initializes the parser with optional resolvers, options, and extra vocabulary. Missing resolver keys receive default instances; extraVocabulary defaults to new DefaultVocabulary().

```php
public function __construct(
    array $resolvers = [],
    array $options = [],
    ?Vocabulary $extraVocabulary = null
)
```

--------------------------------

### Helper::$useBCMath and Helper::$numberScale

Source: https://github.com/opis/json-schema

These public static properties control numeric precision in the Helper::isMultipleOf method. Set useBCMath to false to disable BCMath usage, and adjust numberScale to change the scale used in calculations.

```APIDOC
## Helper::$useBCMath and Helper::$numberScale

### Description
These public static properties control numeric precision in the `Helper::isMultipleOf` method.

### Properties
- **useBCMath** (bool) - Default `true` - When `true`, uses BCMath for arbitrary precision arithmetic.
- **numberScale** (int) - Default `14` - The scale (number of decimal digits) used in BCMath operations.

### Usage
```php
Opis\JsonSchema\Helper::$useBCMath = false;
Opis\JsonSchema\Helper::$numberScale = 20;
```
```

--------------------------------

### Read context inside a custom Filter (PriceFilter)

Source: https://github.com/opis/json-schema

Use ValidationContext methods to access current data, root data, globals, full data path, and data type inside a custom Filter. The example checks if the current value is numeric and within a budget from root data.

```php
use Opis\JsonSchema\{Filter, Schema, ValidationContext};

final class PriceFilter implements Filter
{
    public function validate(ValidationContext $context, Schema $schema, array $args = []): bool
    {
        $value = $context->currentData();
        $max = $context->rootData()->budget ?? 0;         // root access
        $global = $context->globals()['currency'] ?? 'USD';
        $fullPath = $context->fullDataPath();             // e.g. ["items", 0, "price"]
        $type = $context->currentDataType();              // "number"

        return is_numeric($value) && $value <= $max;
    }
}
```

--------------------------------

### Draft::__construct

Source: https://github.com/opis/json-schema

Creates a new Draft instance, optionally accepting an extra vocabulary to merge. This is the constructor for the abstract Draft class.

```APIDOC
## Draft::__construct

### Description
Creates a new Draft instance, optionally accepting an extra vocabulary to merge.

### Method
`__construct`

### Signature
```php
public function __construct(?Vocabulary $extraVocabulary = null)
```

### Parameters
- **$extraVocabulary** (?Vocabulary) - Optional - An extra vocabulary to merge into the draft.

### Returns
No return value (constructor).
```

--------------------------------

### createAbsolute()

Source: https://github.com/opis/json-schema

Builds an absolute pointer.

```APIDOC
## createAbsolute()

### Description
Builds an absolute pointer.

### Method
`createAbsolute()`

### Signature
`(array $path): self`

### Parameters
- **$path** (array) - Required - Path segments.

### Return Value
- **self** - Absolute pointer instance.
```

--------------------------------

### Error reporting with DataInfo

Source: https://github.com/opis/json-schema

Shows how to use DataInfo to access error data and schema information after a validation failure. The example validates an object with a nested array and outputs the offending value, type, full path, and root data, plus schema draft, path, and ID base root.

```php
use Opis\JsonSchema\Validator;

$validator = new Validator();
$error = $validator->dataValidation(
    (object) ['users' => [['age' => 10]]],
    (object) ['properties' => (object) [
        'users' => (object) ['items' => (object) ['properties' => (object) [
            'age' => (object) ['type' => 'integer', 'minimum' => 18],
        ]]],
    ]]
);

if ($error) {
    $data = $error->data();
    echo $data->value();                        // 10
    echo $data->type();                         // "integer"
    echo implode('.', $data->fullPath());       // users.0.age
    echo $data->root()->users[0]->age;          // 10

    $schemaInfo = $error->schema()->info();
    echo $schemaInfo->draft();                  // "2020-12"
    echo $schemaInfo->path();                   // ["properties","users","items"]
    echo $schemaInfo->idBaseRoot();             // Uri|null
}
```

--------------------------------

### Using VariablesContainer with $ref, $each, and default

Source: https://github.com/opis/json-schema

Shows how to build a template with absolute and relative $ref pointers, $each for per-element mapping, and a default fallback. The VariablesContainer resolves the template against sample data, demonstrating output for each key. Relative pointers resolve against the provided path.

```php
use Opis\JsonSchema\Variables\VariablesContainer;

$template = (object) [
    'name'   => (object) ['$ref' => '#/name'],        // absolute pointer
    'sibling' => (object) ['$ref' => '0/sibling'],     // relative pointer (level 0)
    'tags'   => (object) [
        '$ref'  => '#/groups',
        '$each' => (object) ['$ref' => '#/$data/$each/0'],
    ],
    'fallback' => (object) [
        '$ref'    => '#/missing',
        'default' => 'n/a',
    ],
];

$vars = new VariablesContainer($template);
$data = (object) [
    'name'   => 'Widget',
    'groups' => ['a', 'b'],
    'sibling'=> 'W',
];

$resolved = $vars->resolve($data, ['items', 0]);
echo $resolved->name;        // "Widget"
echo $resolved->sibling;     // "W"  ($ref resolves relative to path ['items', 0])
echo $resolved->tags;        // ['a', 'b'] via $each
echo $resolved->fallback;    // "n/a"
```

--------------------------------

### RecursiveRefKeyword constructor

Source: https://github.com/opis/json-schema

Handles draft-2019-09 $recursiveRef/$recursiveAnchor (registered as a variation of $ref in Draft201909; draft 2020-12 uses $dynamicRef/$dynamicAnchor through the same mechanism).

```php
class RecursiveRefKeyword extends AbstractRefKeyword
{
    public function __construct(
        Uri $uri,
        ?Variables $mapper,
        ?Variables $globals,
        ?array $slots = null,
        string $keyword = '$recursiveRef',
        string $anchor = '$recursiveAnchor',
        $anchorValue = true
    )
}
```

--------------------------------

### Register raw schemas and validate by URI

Source: https://github.com/opis/json-schema

Shows how to register a raw schema with a SchemaResolver, create a SchemaLoader, load the schema by URI, and validate data. The commented line demonstrates an alternative registerRaw call with an object.

```php
use Opis\JsonSchema\{Validator, SchemaLoader};
use Opis\JsonSchema\Resolvers\SchemaResolver;
use Opis\JsonSchema\Parsers\SchemaParser;

$resolver = new SchemaResolver();
$resolver->registerRaw(
    file_get_contents(__DIR__ . '/product.schema.json'),
    'https://example.com/schemas/product'
);
// or: $resolver->registerRaw((object) ['type' => 'object'], 'https://example.com/schemas/product');

$loader = new SchemaLoader(new SchemaParser(), $resolver);
$schema = $loader->loadSchemaById(\Opis\JsonSchema\Uri::parse('https://example.com/schemas/product', true));

$validator = new Validator($loader);
$result = $validator->schemaValidation($data, $schema);
```

--------------------------------

### URIRefKeyword constructor

Source: https://github.com/opis/json-schema

Resolves $uri (absolute or fragment-bearing) via the loader — the ordinary $ref case. Throws UnresolvedReferenceException((string)$this->uri, $schema, $context) when the schema is not found (src/Keywords/URIRefKeyword.php:48).

```php
class URIRefKeyword extends AbstractRefKeyword
{
    public function __construct(
        Uri $uri,
        ?Variables $mapper,
        ?Variables $globals,
        ?array $slots = null,
        string $keyword = '$ref'
    )
}
```

--------------------------------

### pathToFragment()

Source: https://github.com/opis/json-schema

Returns a #/... URI fragment form.

```APIDOC
## pathToFragment()

### Description
Returns a `#/...` URI fragment form.

### Method
`pathToFragment()`

### Signature
`(array $path): string`

### Parameters
- **$path** (array) - Required - Path segments.

### Return Value
- **string** - URI fragment string.
```

--------------------------------

### Configure Validator with custom SchemaParser and SchemaResolver

Source: https://github.com/opis/json-schema

Builds a custom Validator with a SchemaResolver that registers a 'file' protocol, a SchemaParser with format resolution and custom options (allowFilters, defaultDraft, decodeContent), and a Validator with max_errors and stop_at_first_error. Use this to fully customize schema loading and validation behavior.

```php
use Opis\JsonSchema\{Validator, SchemaLoader};
use Opis\JsonSchema\Parsers\SchemaParser;
use Opis\JsonSchema\Resolvers\{SchemaResolver, FormatResolver};

$resolver = new SchemaResolver();
$resolver->registerProtocol('file', fn($uri) => file_get_contents($uri->path()));

$parser = new SchemaParser(
    ['format' => new FormatResolver()],
    [
        'allowFilters' => false,
        'defaultDraft' => '2020-12',
        'decodeContent' => ['06', '07', '2019-09'],
    ]
);

$validator = new Validator(new SchemaLoader($parser, $resolver), max_errors: 10, stop_at_first_error: false);
```

--------------------------------

### getFormatResolver

Source: https://github.com/opis/json-schema

Returns the current format resolver, or null if not set.

```APIDOC
## getFormatResolver

### Description
Returns the current format resolver, or null if not set.

### Method
getFormatResolver

### Signature
```php
public function getFormatResolver(): ?FormatResolver
```

### Return Value
?FormatResolver - The format resolver or null.
```

--------------------------------

### FilterResolver constructor

Source: https://github.com/opis/json-schema

Creates a FilterResolver with optional namespace separator and default namespace.

```APIDOC
## FilterResolver::__construct()

### Description
Creates a FilterResolver instance.

### Method
`new FilterResolver(?string $ns_separator = '::', ?string $default_ns = 'default')`

### Parameters
- **$ns_separator** (string|null) - Optional - Namespace separator, defaults to `'::'`.
- **$default_ns** (string|null) - Optional - Default namespace, defaults to `'default'`.
```

--------------------------------

### Use context derivation and path navigation in a custom Keyword (MyKeyword)

Source: https://github.com/opis/json-schema

Shows how to create a derived context, push/pop data path, and access current data in a custom Keyword. Always restore the data path with popDataPath() after modifications.

```php
use Opis\JsonSchema\{Keyword, Schema, ValidationContext};

final class MyKeyword implements Keyword
{
    public function validate(ValidationContext $context, Schema $schema): ?\Opis\JsonSchema\Errors\ValidationError
    {
        $child = $context->create($schema);         // new context, $mapper=null
        $context->pushDataPath('extra');
        $error = $child->newInstance($context->currentData(), $schema)->currentData() /* ... */;
        $context->popDataPath();                    // always restore
        return null;
    }
}
```

--------------------------------

### option

Source: https://github.com/opis/json-schema

Returns the configured value for a given option name, or a default value if not set.

```APIDOC
## option

### Description
Returns the configured value for a given option name, or a default value if not set.

### Method
option

### Signature
```php
public function option(string $name, $default = null)
```

### Parameters
- `$name` (string) - Required - The option name.
- `$default` (mixed) - Optional - Default value to return if option is not set.

### Return Value
mixed|null - The configured value or `$default`.
```

--------------------------------

### DateTimeFilters class signature

Source: https://github.com/opis/json-schema

Provides static date/time comparison filters. All methods accept args['value'] as the comparison bound and optional args['timezone'] as an IANA timezone name. Date comparisons are date-only, DateTime comparisons use full instants, and Time comparisons use the 1970-01-01 day. Invalid bounds or timezones cause the DateTime constructor to throw an uncaught exception.

```php
final class DateTimeFilters
{
    public static function MinDate(string $date, array $args): bool
    public static function MaxDate(string $date, array $args): bool
    public static function NotDate(string $date, array $args): bool
    public static function MinTime(string $time, array $args): bool
    public static function MaxTime(string $time, array $args): bool
    public static function MinDateTime(string $date, array $args): bool
    public static function MaxDateTime(string $date, array $args): bool
}
```

--------------------------------

### KeywordParserTrait helpers

Source: https://github.com/opis/json-schema

Provides the constructor and helper methods for keyword parsers. keywordExists and keywordValue accept either a raw schema object or a SchemaInfo. keywordException substitutes {keyword} in the message.

```php
trait KeywordParserTrait
{
    protected string $keyword;
    public function __construct(string $keyword)
    protected function keywordExists(object $schema, ?string $keyword = null): bool
    protected function keywordValue(object $schema, ?string $keyword = null)
    protected function keywordException(string $message, SchemaInfo $info, ?string $keyword = null): InvalidKeywordException
}
```

--------------------------------

### supportedDrafts

Source: https://github.com/opis/json-schema

Returns a list of all supported draft version keys.

```APIDOC
## supportedDrafts

### Description
Returns a list of all supported draft version keys.

### Method
supportedDrafts

### Signature
```php
public function supportedDrafts(): array
```

### Return Value
array - An array of draft version strings.
```

--------------------------------

### Draft handling methods

Source: https://github.com/opis/json-schema

defaultDraftVersion() reads the defaultDraft option. draft() returns the Draft vocabulary for a version or null. addDraft() registers custom drafts; supportedDrafts() lists all version keys.

```php
public function defaultDraftVersion(): string
public function setDefaultDraftVersion(string $draft): self
public function draft(string $version): ?Draft
public function addDraft(Draft $draft): self
public function supportedDrafts(): array   // string[]
```

--------------------------------

### parser()/setParser() and resolver()/setResolver() methods

Source: https://github.com/opis/json-schema

Fluent accessors for the composition. Validator::setParser()/setResolver() delegate to these.

```php
public function parser(): SchemaParser
public function setParser(SchemaParser $parser): self
public function resolver(): ?SchemaResolver
public function setResolver(?SchemaResolver $resolver): self
```

--------------------------------

### path()

Source: https://github.com/opis/json-schema

Returns the decoded path segments.

```APIDOC
## path()

### Description
Returns the decoded path segments.

### Method
`path()`

### Signature
`(): array`

### Return Value
- **array** - Decoded path segments.
```

--------------------------------

### Add opis/json-schema ^2.6 to composer.json

Source: https://github.com/opis/json-schema/blob/master/README.md

Directly reference the package as a dependency in your composer.json file.

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