Opis JSON Schema

https://opis.io/json-schema
Admin
A PHP implementation of the JSON Schema standard for validating JSON documents, supporting modern...
Tokens:39,456
Snippets:500
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### JSON Schema with 'examples' keyword

Source: https://opis.io/json-schema/2.x/structure.html

Shows how to use the 'examples' keyword to list valid data instances for the schema.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "http://example.com/number.json#",
  "title": "Test if it is a number",
  "description": "A data is considered a number if is an integer or a float.",
  "examples": [-5.10, -2, 0, 5, 8.10],
  
  "type": "number"
}
```

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

### Relative Pointer Examples from /price

Source: https://opis.io/json-schema/2.x/pointers.html

Demonstrates various relative JSON pointers starting from the '/price' location (value: 10.5). Shows how to access current value, parent property name, parent document, and nested properties.

```json
Pointer | Value  
---|---
`0` | `10.5`  
`0#` | `"price"`  
`1` | _the document itself (root)_  
`1#` | _error_  
`1/name` | `"some product"`  
`1/info` | `{"onStock": true}`  
`1/info/onStock` | `true`  
`1/a~1b` | `"a"`  
`1/inexstent/path` | _error_  
`2` | _error_  
```

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

### Install Opis JSON Schema with Composer

Source: https://opis.io/json-schema/2.x

Install the library using Composer from the command line.

```bash
composer require opis/json-schema

```

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

### Relative Pointer Examples from /features/1/url

Source: https://opis.io/json-schema/2.x/pointers.html

Illustrates relative JSON pointers starting from the '/features/1/url' location (value: "http://example.com"). Covers accessing current value, property name, parent array index, and navigating up multiple levels.

```json
Pointer | Value  
---|---
`0` | `"http://example.com"`  
`0#` | `"url"`  
`1#` | `1` (array index)  
`1/name` | `"environment friendly"`  
`2#` | `"features"`  
`2/0` | `"easy to use"`  
`1-1` | `"easy to use"`  
`2/0#` | `0` (array index)  
`3` | _the document itself (root)_  
`3/price` | `10.5`  
`3/info/onStock` | `true`  
`3/inexstent/path` | _error_  
`3#` | _error_  
`4` | _error_  
```

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

### Path Expansion Example

Source: https://opis.io/json-schema/2.x/uri-template.html

Shows how to use URI templates for path expansion, where variables are joined by slashes.

```json
{
  "$ref": "{/var1,var2}",
  "$vars": {
    "var1": "a",
    "var2": "b"
  }
}

```

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

### Fragment Expansion Example

Source: https://opis.io/json-schema/2.x/uri-template.html

Shows how to use URI templates for fragment expansion, where variables are appended after a hash symbol.

```json
{
  "$ref": "{#var1}",
  "$vars": {
    "var1": "test"
  }
}

```

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

### JSON Document Structure

Source: https://opis.io/json-schema/2.x/pointers.html

This is the example JSON document used to illustrate relative pointer navigation.

```json
{
  "name": "some product",
  "price": 10.5,
  "features": [
    "easy to use",
    {
      "name": "environment friendly",
      "url": "http://example.com"
    }
  ],
  "info": {
    "onStock": true
  },
  "a/b": "a"
}

```

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

### propertyNames Example

Source: https://opis.io/json-schema/2.x/object.html

All property names in an object must have a minimum length of 2 characters.

```json
{
  "type": "object",
  "propertyNames": {
    "type": "string",
    "minLength": 2
  }
}
```

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

### patternProperties Example

Source: https://opis.io/json-schema/2.x/object.html

Defines schemas for properties whose names match specific regular expressions. Properties starting with 'str-' must be strings, and those starting with 'int-' must be integers.

```json
{
  "type": "object",
  "patternProperties": {
    "^str-": {
      "type": "string"
    },
    "^int-": {
      "type": "integer"
    }
  }
}
```

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

### minProperties Example

Source: https://opis.io/json-schema/2.x/object.html

An object must contain at least 2 properties to be valid.

```json
{
  "type": "object",
  "minProperties": 2
}
```

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

### Query String Expansion Example

Source: https://opis.io/json-schema/2.x/uri-template.html

Illustrates URI template usage for query string expansion, where variables are appended as key-value pairs.

```json
{
  "$ref": "{?var1,var2}",
  "$vars": {
    "var1": "a",
    "var2": "b"
  }
}

```

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

### maxProperties Example

Source: https://opis.io/json-schema/2.x/object.html

An object can have at most 2 properties to be valid.

```json
{
  "type": "object",
  "maxProperties": 2
}
```

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

### allOf Schema Example

Source: https://opis.io/json-schema/2.x/multiple-subschemas.html

Use 'allOf' when an instance must be valid against all of the provided subschemas. The value must be an array of schemas.

```json
{
  "allOf": [
    {"minLength": 2},
    {"pattern": "^a"}
  ]
}
```

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

### Example User Data

Source: https://opis.io/json-schema/2.x/quick-start.html

This JSON represents the data structure for a user profile that will be validated.

```json
{
    "name": "John Doe",
    "age": 31,
    "email": "john@example.com",
    "website": null,
    "location": {
        "country": "US",
        "address": "Sesame Street, no. 5"
    },
    "available_for_hire": true,
    "interests": ["php", "html", "css", "javascript", "programming", "web design"],
    "skills": [
        {
            "name": "HTML",
            "value": 100
        },
        {
            "name": "PHP",
            "value": 55
        },
        {
            "name": "CSS",
            "value": 99.5
        },
        {
            "name": "JavaScript",
            "value": 75
        }
    ]
}

```

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

### Register a Prime Number Format Class (1.x)

Source: https://opis.io/json-schema/2.x/php-migration.html

In 1.x, formats were registered with a FormatContainer. This example shows registering the PrimeNumberFormat class.

```php
use Opis\JsonSchema{
    Validator,
    FormatContainer
};

// Create a new FormatContainer
$formats = new FormatContainer();

// Register our prime format
// Class PrimeNumberFormat is defined in the above example
$formats->add("integer", "prime", new PrimeNumberFormat());

// Create a IValidator
$validator = new Validator();

// Set formats to be used by validator
$validator->setFormats($formats);

```

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

### General $map Example

Source: https://opis.io/json-schema/2.x/mappers.html

Demonstrates how $map transforms data before it's validated against a referenced schema.

```json
{
    "$ref": "some-ref.json",
    "$map": {
        "prop1": 1,
        "prop2": "something",
        "dynamic-prop": {"$ref": "/dynamic"}
    }
}
```

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

### Basic Validator Setup and Data Validation

Source: https://opis.io/json-schema/2.x/php-error-formatter.html

This snippet sets up a basic validator, registers a schema, and validates sample data. It demonstrates the initial steps required before error formatting can be applied. The `setMaxErrors` method limits the number of errors reported.

```php
use Opis\JsonSchema{
    Validator,
    JsonPointer,
    ValidationResult,
};
use Opis\JsonSchema\Errors\{
    ErrorFormatter,
    ValidationError,
};

// Create a new validator
$validator = new Validator();

// Set max errors
$validator->setMaxErrors(5);

// Register a schema
$validator->resolver()->registerRaw(
<<<'JSON'
{
    "$id": "http://example.com/user.json",
    
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 100
        },
        "age": {
            "type": "integer",
            "minimum": 18,
            "maximum": 65
        }
    },
    
    "required": ["name", "age"]
}
JSON
);

// Our data
$data = (object)[
    'name' => 'A',
    'age' => 17,
];

/** @var ValidationResult $result */
$result = $validator->validate($data, 'http://example.com/user.json');

if ($result->isValid()) {
    // No errors here
    echo "Valid", PHP_EOL;
} else {
    // Get the error
    $error = $result->error();

    // Create an error formatter
    $formatter = new ErrorFormatter();

    // Print helper
    $print = function ($value) {
        echo json_encode(
            $value,
            JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
            ),
            PHP_EOL;
        echo '-----------', PHP_EOL;
    };

    // Each format method is presented below
    // ...
}

```

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

### Register a Modulo Filter Class (1.x)

Source: https://opis.io/json-schema/2.x/php-migration.html

In 1.x, filters were registered with a FilterContainer. This example shows registering the ModuloFilter class.

```php
use Opis\JsonSchema{
    Validator,
    FilterContainer
};

// Create a new FilterContainer
$filters = new FilterContainer();

// Register our modulo filter
// Class ModuleFilter is defined in the above example
$filters->add("integer", "modulo", new ModuloFilter());

// Create a validator
$validator = new Validator();

// Set filters to be used by validator
$validator->setFilters($filters);

```

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

### Example JSON Document for Pointers

Source: https://opis.io/json-schema/2.x/pointers.html

This JSON document serves as a reference for demonstrating how JSON pointers navigate its structure. It includes various data types and a key with a slash character.

```json
{
  "name": "some product",
  "price": 10.5,
  "features": [
    "easy to use",
    {
      "name": "environment friendly",
      "url": "http://example.com"
    }
  ],
  "info": {
    "onStock": true
  },
  "a/b": "a"
}
```

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

### anyOf Schema Example

Source: https://opis.io/json-schema/2.x/multiple-subschemas.html

Use 'anyOf' when an instance must be valid against at least one of the provided subschemas. The value must be an array of schemas.

```json
{
  "type": "array",
  "anyOf": [
    {
      "contains": {"const": 0}
    },
    {
      "contains": {"const": "ok"}
    }
  ]
}
```

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

### formatFlat Method Examples

Source: https://opis.io/json-schema/2.x/php-error-formatter.html

Illustrates the use of the formatFlat method with default and custom formatting. The default method returns a flat array of error messages, while a custom callback allows for detailed error objects.

```php
// default
$print($formatter->formatFlat($error));

$custom = function (ValidationError $error) use ($formatter) {
    return [
        'keyword' => $error->keyword(),
        'message' => $formatter->formatErrorMessage($error),

        'dataPath' => $formatter->formatErrorKey($error),
        'dataValue' => $error->data()->value(),
    ];
};

// custom
$print($formatter->formatFlat($error, $custom));
```

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

### formatOutput Method Examples

Source: https://opis.io/json-schema/2.x/php-error-formatter.html

Demonstrates using the formatOutput method with different predefined format types: flag, basic, detailed, and verbose. Each format provides a different level of detail for the validation error.

```php
$print($formatter->formatOutput($error, "flag"));
$print($formatter->formatOutput($error, "basic"));
$print($formatter->formatOutput($error, "detailed"));
$print($formatter->formatOutput($error, "verbose"));
```

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

### Example of Max Errors Behavior (Extended)

Source: https://opis.io/json-schema/2.x/php-validator.html

Illustrates the effect of a higher 'maxErrors' value. With 'maxErrors' set to 5, multiple validation failures within a keyword like 'properties' are reported, including errors for both 'name' and 'age' in this example.

```json
{
    "keyword": "properties",
    "message": "The properties must match schema: name, age",
    "subErrors": [
        {
            "keyword": "minLength",
            "message": "Minimum string length is 3, found 2"
        },
        {
            "keyword": "minimum",
            "message": "Number must be greater than or equal to 18"
        }
    ]
}

```

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

### Extensible Tree Schema with $recursiveAnchor

Source: https://opis.io/json-schema/2.x/references.html

An example of an extensible schema for a tree structure using $recursiveAnchor and $recursiveRef.

```json
{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "https://example.com/tree",
  "$recursiveAnchor": true,

  "type": "object",
  "properties": {
    "data": true,
    "children": {
      "type": "array",
      "items": {
        "$recursiveRef": "#"
      }
    }
  }
}
```

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

### Register a Callable Prime Number Format (2.x)

Source: https://opis.io/json-schema/2.x/php-migration.html

In 2.x, callable formats are registered with the FormatResolver. This example registers a prime number format.

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

$validator = new Validator();

/** @var FormatResolver $formats */
$formats = $validator->parser()->getFormatResolver();

// Register our prime number format
$formats->registerCallable("integer", "prime", function (int $value): bool {
    // See the example above for the function contents
});

```

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

### Register a Callable Modulo Filter (2.x)

Source: https://opis.io/json-schema/2.x/php-migration.html

In 2.x, callable filters are registered with the FilterResolver. This example registers the previously defined modulo filter.

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

$validator = new Validator();

/** @var FilterResolver $filters */
$filters = $validator->parser()->getFilterResolver();

$modulo = function (int $value, array $args): bool {
    $divisor = $args['divisor'] ?? 1;
    $reminder = $args['reminder'] ?? 0;
    return $value % $divisor == $reminder;
};

// Register our modulo filter
$filters->registerCallable("integer", "modulo", $modulo);

```

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

### dependentRequired Example

Source: https://opis.io/json-schema/2.x/object.html

If an object has the property 'a', then it must also have properties 'b' and 'c'.

```json
{
  "type": "object",
  "dependentRequired": {
    "a": ["b", "c"]
  }
}
```

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

### Compositions Modifier Example

Source: https://opis.io/json-schema/2.x/uri-template.html

Demonstrates the compositions modifier in URI templates, used for expanding objects into query string parameters.

```json
{
  "$ref": "{?address*}",
  "$vars": {
    "address": {
      "city": "Some city",
      "street": "Some street",
      "number": 5
    }
  }
}

```

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

### dependentSchemas Example

Source: https://opis.io/json-schema/2.x/object.html

If an object has the property 'c', then the property 'b' must be an integer.

```json
{
  "type": "object",
  "dependentSchemas": {
    "c": {
      "type": "object",
      "properties": {
        "b": {
          "type": "integer"
        }
      }
    }
  }
}
```

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

### Default Multiple Errors Output

Source: https://opis.io/json-schema/2.x/php-error-formatter.html

Example JSON output for multiple validation errors formatted using default settings.

```json
{
  "/name": [
    "Minimum string length is 2, found 1"
  ],
  "/age": [
    "Number must be greater than or equal to 18"
  ]
}

```

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

### oneOf Schema Example

Source: https://opis.io/json-schema/2.x/multiple-subschemas.html

Use 'oneOf' when an instance must be valid against exactly one of the provided subschemas. The value must be an array of schemas.

```json
{
  "type": "array",
  "items": {
    "type": "number"
  },
  "oneOf": [
    {
      "items": {
        "exclusiveMinimum": 0
      }
    },
    {
      "items": {
        "exclusiveMaximum": 0
      }
    },
    {
      "items": {
        "const": 0
      }
    }
  ]
}
```

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

### formatNested Method Examples

Source: https://opis.io/json-schema/2.x/php-error-formatter.html

Shows how to use the formatNested method with both default and custom callback functions. The default format provides a nested JSON structure, while a custom callback allows for specific field selection.

```php
// default
$print($formatter->formatNested($error));

$custom = function (ValidationError $error, ?array $subErrors = null) use ($formatter) {
    $ret = [
        'keyword' => $error->keyword(),
        'message' => $formatter->formatErrorMessage($error),
    ];

    if ($subErrors) {
        $ret['subErrors'] = $subErrors;
    }

    return $ret;
};

// custom
$print($formatter->formatNested($error, $custom));
```

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

### Define a Prime Number Format as a Class (1.x)

Source: https://opis.io/json-schema/2.x/php-migration.html

In 1.x, formats were implemented as classes adhering to the IFormat interface. This example shows a prime number format class.

```php
use Opis\JsonSchema\IFormat;

class PrimeNumberFormat implements IFormat
{
    public function validate($data): bool {
        if ($data < 2) {
            return false;
        }
        if ($data == 2) {
            return true;
        }
        $max = floor(sqrt($data)) + 1;
        for ($i = 3; $i < $max; $i += 2) {
            if ($data % $i == 0) {
                return false;
            }
        }
        
        return true;
    }
}

```

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

### Define a Modulo Filter as a Class (1.x)

Source: https://opis.io/json-schema/2.x/php-migration.html

In 1.x, filters were implemented as classes that adhere to the IFilter interface. This example shows a modulo filter class.

```php
use Opis\JsonSchema\IFilter;

class ModuloFilter implements IFilter
{
    public function validate($value, array $args): bool {
        $divisor = $args['divisor'] ?? 1;
        $reminder = $args['reminder'] ?? 0;
        return $value % $divisor == $reminder;
    }
}

```

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

### Schema: Accept anything but strings

Source: https://opis.io/json-schema/2.x/conditional-subschemas.html

Use the 'not' keyword to define a schema that an instance must not validate against. This example ensures the instance is not of type string.

```json
{
  "not": {
    "type": "string"
  }
}
```

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

### Accessing the Resolver

Source: https://opis.io/json-schema/2.x/php-loader.html

Shows how to get the Resolver instance, which is used to resolve schema contents by URI. The resolver can be accessed either through the Validator or directly from the SchemaLoader.

```php
use Opis\
JsonSchema\Validator;

$validator = new Validator();

// Get the resolver from schema loader
$resolver = $validator->loader()->resolver();

// Or, get it using the shortcut
$resolver = $validator->resolver();
```

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

### Define a Modulo Filter as a Callable (2.x)

Source: https://opis.io/json-schema/2.x/php-migration.html

In 2.x, filters can be defined as anonymous functions (callables). This example shows a modulo filter.

```php
$modulo_filter = function (int $value, array $args): bool {
    $divisor = $args['divisor'] ?? 1;
    $reminder = $args['reminder'] ?? 0;
    return $value % $divisor == $reminder;
};

```

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

### JSON Schema with $ref Examples

Source: https://opis.io/json-schema/2.x/pointers.html

This schema demonstrates the use of the '$ref' keyword to reference subschemas within the same document, other local documents, and external documents. The '$id' keyword is crucial for resolving these references.

```json
{
  "$id": "http://example.com/path/to/user.json",
  
  "type": "object",
  "properties": {
    "email": {
      "$ref": "#/$defs/personal/email"
    },
    "birthday": {
      "$ref": "#/$defs/personal/birthday"
    },
    "settings": {
      "$ref": "user-settings.json#/$defs/settings"
    },
    "info": {
      "$ref": "../info.json#"
    },
    "root": {
      "$ref": "/other/path/to/schema.json#/$defs/root"
    },
    "external": {
      "$ref": "http://external.example.com/some-schema.json#/$defs/name"
    }
  },
  
  "$defs": {
    "personal": {
      "email": {
        "type": "string",
        "format": "email"
      },
      "birthday": {
        "type": "string",
        "format": "date"
      }
    }
  }
}

```

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

### Example Output for Multiple Errors

Source: https://opis.io/json-schema/2.x/php-validator.html

Shows the formatted output when 'stopAtFirstError' is disabled and a single property violates multiple schema rules. Both the minLength and pattern validation failures are listed for the 'value' property.

```json
{
    "/value": [
        "Minimum string length is 10, found 1",
        "The string should match pattern: ^a"
    ]
}

```

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

### Define a Prime Number Format as a Callable (2.x)

Source: https://opis.io/json-schema/2.x/php-migration.html

In 2.x, formats can be defined as anonymous functions. This example defines a prime number format checker.

```php
$prime_number = function (int $data): bool {
    if ($data < 2) {
        return false;
    }
    if ($data == 2) {
        return true;
    }
    $max = floor(sqrt($data)) + 1;
    for ($i = 3; $i < $max; $i += 2) {
        if ($data % $i == 0) {
            return false;
        }
    }
    
    return true;
};

```

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

### Custom Multiple Errors Output

Source: https://opis.io/json-schema/2.x/php-error-formatter.html

Example JSON output for multiple validation errors formatted with custom logic, providing detailed information for each error.

```json
{
  "name": [
    {
      "schema": {
        "id": null,
        "base": "http://example.com/user.json#",
        "root": "http://example.com/user.json#",
        "draft": "2020-12",
        "path": "#/properties/name",
        "contents": {
          "type": "string",
          "minLength": 2,
          "maxLength": 100
        }
      },
      "error": {
        "keyword": "minLength",
        "args": {
          "min": 2,
          "length": 1
        },
        "message": "Minimum string length is {min}, found {length}",
        "formattedMessage": "Minimum string length is 2, found 1"
      },
      "data": {
        "type": "string",
        "value": "A",
        "fullPath": [
          "name"
        ]
      }
    }
  ],
  "age": [
    {
      "schema": {
        "id": null,
        "base": "http://example.com/user.json#",
        "root": "http://example.com/user.json#",
        "draft": "2020-12",
        "path": "#/properties/age",
        "contents": {
          "type": "integer",
          "minimum": 18,
          "maximum": 65
        }
      },
      "error": {
        "keyword": "minimum",
        "args": {
          "min": 18
        },
        "message": "Number must be greater than or equal to {min}",
        "formattedMessage": "Number must be greater than or equal to 18"
      },
      "data": {
        "type": "integer",
        "value": 17,
        "fullPath": [
          "age"
        ]
      }
    }
  ]
}

```

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

### Injecting Slots to Customize User Validation

Source: https://opis.io/json-schema/2.x/slots.html

Injects specific validation rules for 'name-prop' and 'age-prop' slots. This example sets length constraints for the name and a range for the age.

```json
{
 "$ref": "http://example.com/user.json",

 "$inject": {
  "name-prop": {
   "minLength": 3,
   "maxLength": 20
  },
  "age-prop": {
   "minimum": 21,
   "maximum": 65
  }
 }
}

```

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

### Example of Max Errors Behavior (Limited)

Source: https://opis.io/json-schema/2.x/php-validator.html

Demonstrates how 'maxErrors' limits the number of validation errors reported. When set to 1, only the first encountered error for a keyword like 'properties' is shown, and subsequent validations are skipped.

```json
{
    "keyword": "properties",
    "message": "The properties must match schema: name",
    "subErrors": [
        {
            "keyword": "minLength",
            "message": "Minimum string length is 3, found 2"
        }
    ]
}

```

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

### Complete JSON Schema Example

Source: https://opis.io/json-schema/2.x/quick-start.html

A comprehensive JSON schema defining an object with various properties including strings, integers, emails, URLs, nested objects, booleans, arrays of strings, and arrays of objects. It specifies required fields and disallows additional properties.

```json
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "http://api.example.com/profile.json",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "pattern": "^[a-zA-Z0-9\\-]+(\\s[a-zA-Z0-9\\-]+)*$"
        },
        "age": {
            "type": "integer",
            "minimum": 18,
            "maximum": 100
        },
        "email": {
            "type": "string",
            "maxLength": 128,
            "format": "email"
        },
        "website": {
            "type": ["string", "null"],
            "maxLength": 128,
            "format": "hostname"
        },
        "location": {
            "type": "object",
            "properties": {
                 "country": {
                     "enum": ["US", "CA", "GB"]
                 },
                 "address": {
                     "type": "string",
                     "maxLength": 128
                 }
            },
            "required": ["country", "address"],
            "additionalProperties": false
        },
        "available_for_hire": {
            "type": "boolean"
        },
        "interests": {
            "type": "array",
            "minItems": 3,
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
                "type": "string",
                "maxLength": 64
            }
        },
        "skills": {
            "type": "array",
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "minLenght": 1,
                        "maxLength": 64
                    },
                    "value": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 100,
                        "multipleOf": 0.25
                    }
                },
                "required": ["name", "value"],
                "additionalProperties": false
            }
        }
    },
    "required": ["name", "age", "email", "location", 
                 "available_for_hire", "interests", "skills"],
    "additionalProperties": false
}
```

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

### Validate Data with Multiple Errors per Property

Source: https://opis.io/json-schema/2.x/php-validator.html

This example demonstrates validating data where a single property fails multiple schema constraints (minLength and pattern). It requires 'stopAtFirstError' to be disabled to report both failures.

```php
use Opis\JsonSchema\{
    Validator,
    ValidationResult,
    Errors\ErrorFormatter,
};

$schema = <<<'JSON'
{
  "type": "object",
  "properties": {
    "value": {
      "type": "string",
      "minLength": 10,
      "pattern": "^a"
    }
  }
}
JSON;

$data = (object)[
    "value" => "b",
];

$validator = new Validator();
$validator->setMaxErrors(10);
$validator->setStopAtFirstError(false);

/** @var ValidationResult $result */
$result = $validator->validate($data, $schema);

if ($result->isValid()) {
    echo "Valid";
} else {
    echo json_encode(
        (new ErrorFormatter())->format($result->error()),
        JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
    );
}


```

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

### Registering a Protocol Directory with Host

Source: https://opis.io/json-schema/2.x/php-loader.html

The `registerProtocolDir` method is similar to `registerPrefix` but also specifies a host. It maps a local directory to a specific URI scheme and host combination, prefixing resolved files with `scheme://host/`.

```php
$resolver->registerProtocolDir('http', 'example.com', '/path/to/dir');
```

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

### Basic URI Template Expansion

Source: https://opis.io/json-schema/2.x/uri-template.html

Demonstrates a basic URI template with placeholders for folder and file, which are replaced by values from the $vars keyword.

```json
{
    "$ref": "http://example.com/{folder}/{file}.json",
    "$vars": {
        "folder": "user",
        "file": "schema"
    }
}

```

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

### Registering a Directory for Schema Loading

Source: https://opis.io/json-schema/2.x/php-loader.html

Use `registerPrefix` to map a filesystem directory to a URI prefix. This enables loading schemas from files within that directory using their relative paths prefixed with the specified URI.

```php
$resolver->registerPrefix('http://example.com/','/path/to/dir');
```

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

### registerPrefix method

Source: https://opis.io/json-schema/2.x/php-loader.html

Registers a filesystem directory to load schema files from, mapping it to a specific URI prefix.

```APIDOC
## registerPrefix method

### Description

Use this method to register a filesystem directory from which schema files will be loaded. You must specify the URI prefix that maps to this directory.

### Signature

```php
public function registerPrefix(string $prefix, string $dir): self
```

### Usage Example

```php
// Maps 'http://example.com/' to '/path/to/dir'
$resolver->registerPrefix('http://example.com/','/path/to/dir');

// If '/path/to/dir' contains:
// [user]
//    create.json
//    update.json
// [resume]
//    [hobby]
//         item.json
//    create.json
//    update.json

// The following documents will be available:
// http://example.com/user/create.json
// http://example.com/user/update.json
// http://example.com/resume/create.json
// http://example.com/resume/update.json
// http://example.com/resume/hobby/item.json
```
```

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

### Query String Expansion with Existing Parameters

Source: https://opis.io/json-schema/2.x/uri-template.html

Demonstrates expanding query string parameters in a URI template that already contains fixed query parameters.

```json
{
  "$ref": "?x=1&y=2{&var1,var2}",
  "$vars": {
    "var1": "a",
    "var2": "b"
  }
}

```

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

### Substring Modifier Example

Source: https://opis.io/json-schema/2.x/uri-template.html

Illustrates the substring modifier in URI templates, which limits the expansion of a variable to a specified number of characters.

```json
{
  "$ref": "{var:3}",
  "$vars": {
    "var": "test"
  }
}

```

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

### Instantiating and Configuring Schema Loader

Source: https://opis.io/json-schema/2.x/php-loader.html

Demonstrates how to obtain or create a SchemaLoader instance and associate it with a Validator. The loader is crucial for parsing schema contents, especially when dealing with different JSON Schema drafts.

```php
use Opis\JsonSchema;\n\n// Option 1. - Get the loader from the validator

$validator = new Validator();
$loader = $validator->loader();

// Option 2. - Create the loader
$loader= new SchemaLoader();

// Validator constructor accepts a loader as argument
$validator = new Validator($loader);

// Or you can set the loader
$validator->setLoader($loader);
```

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

### Registering a Schema File

Source: https://opis.io/json-schema/2.x/php-loader.html

The `registerFile` method allows registering a schema from a local file. You must provide a unique ID for the schema and the path to the file.

```php
$resolver->registerFile('http://example.com/schema.json', '/path/to/file.json');
```

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

### Default Single Error Output

Source: https://opis.io/json-schema/2.x/php-error-formatter.html

Example JSON output for a single validation error formatted using default settings.

```json
{
  "/name": "Minimum string length is 2, found 1",
  "/age": "Number must be greater than or equal to 18"
}

```

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

### $anchor and $ref for Schema Referencing

Source: https://opis.io/json-schema/2.x/structure.html

Demonstrates how to use $anchor to define a reusable schema fragment and $ref to reference it. This is crucial for modularizing and reusing schema definitions.

```json
{
 "$id": "http://example.com",
 
 "$ref": "#mail",
 
 "$defs": {
  "mail": {
   "$anchor": "mail",
   "format": "email"
  }
 }
}
```

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

### SchemaLoader Usage

Source: https://opis.io/json-schema/2.x/php-loader.html

Demonstrates how to obtain or create a SchemaLoader instance and associate it with a Validator.

```APIDOC
## SchemaLoader Usage

### Description

This section shows how to get the schema loader from an existing validator instance or create a new one. It also illustrates how to set the loader for a validator.

### Usage Examples

```php
use Opis\JsonSchema\{
    Validator,
    SchemaLoader,
};

// Option 1. - Get the loader from the validator
$validator = new Validator();
$loader = $validator->loader();

// Option 2. - Create the loader
$loader = new SchemaLoader();

// Validator constructor accepts a loader as argument
$validator = new Validator($loader);

// Or you can set the loader
$validator->setLoader($loader);
```
```

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

### Accessing Parser and Resolvers

Source: https://opis.io/json-schema/2.x/php-loader.html

Demonstrates how to retrieve the parser instance from the Validator and access its various resolvers (Filter, Format, Content Encoding, Content Media Type).

```php
use Opis\JsonSchema\Validator;
use Opis\JsonSchema\Resolvers{
    FilterResolver,
    FormatResolver,
    ContentEncodingResolver,
    ContentMediaTypeResolver,
};

$validator = new Validator();

// Get the parser from schema loader
$parser = $validator->loader()->parser();

// Or, by using the shortcut
$parser = $validator->parser();

// Accessing the resolvers...

/** @var FilterResolver $filter_resolver */
$filter_resolver = $parser->getFilterResolver();

/** @var FormatResolver $format_resolver */
$format_resolver = $parser->getFormatResolver();

/** @var ContentEncodingResolver $encoding_resolver */
$encoding_resolver = $parser->getContentEncodingResolver();

/** @var ContentMediaTypeResolver $media_resolver */
$media_resolver = $parser->getMediaTypeResolver();

```

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

### Valid Recursive JSON Input

Source: https://opis.io/json-schema/2.x/definitions.html

An example of valid JSON data that conforms to the recursive schema, showing a simple 'best_friend' relationship.

```json
{
  "name": "John",
  "best_friend": {
    "name": "The dog"
  }
}
```

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

### Format Keyed Errors with Custom Callbacks

Source: https://opis.io/json-schema/2.x/php-error-formatter.html

Demonstrates how to use the formatKeyed method with custom callbacks for both the error key and the error message. The default behavior is shown first, followed by the custom implementation.

```php
// default
$print($formatter->formatKeyed($error));

$custom = function (ValidationError $error) use ($formatter) {
    return [
        'keyword' => $error->keyword(),
        'message' => $formatter->formatErrorMessage($error),
    ];
};

$custom_key = function (ValidationError $error): string {
    $path = implode('.', $error->data()->fullPath());
    return strtoupper($path);
};

// custom
$print($formatter->formatKeyed($error, $custom, $custom_key));

```

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

### JSON Schema with 'description' keyword

Source: https://opis.io/json-schema/2.x/structure.html

Illustrates the 'description' keyword for providing a more detailed explanation of the schema's purpose.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "http://example.com/number.json#",
  "title": "Test if it is a number",
  "description": "A data is considered number if it is an integer or a float.",
  
  "type": "number"
}
```

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

### allOf Schema Never Validates

Source: https://opis.io/json-schema/2.x/multiple-subschemas.html

An 'allOf' schema can also be written to never validate. This example requires an instance to be both a string and a number simultaneously.

```json
{
  "allOf": [
    {"type": "string"},
    {"type": "number"}
  ]
}
```

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

### Basic Format Schema

Source: https://opis.io/json-schema/2.x/formats.html

A simple schema demonstrating the use of the 'format' keyword. This schema expects a string with the 'date' format.

```json
{
    "format": "date"
}

```

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

### PHP Data Handling with Default Address Object

Source: https://opis.io/json-schema/2.x/default-value.html

Illustrates how to access the 'address' property in PHP when it might be missing, requiring manual instantiation of the default object structure.

```php
$data->address ?? (object) [
    'country' => null,
    'county' => null,
    'city' => null,
    'street' => '',
    'street2' => '',
];

```

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

### JSON Schema using Custom Format

Source: https://opis.io/json-schema/2.x/php-format.html

This is an example of a JSON schema that utilizes the custom 'prime' integer format. The schema will validate numbers that are prime.

```json
{
  "type": "integer",
  "format": "prime"
}

```

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

### JSON Schema with 'title' keyword

Source: https://opis.io/json-schema/2.x/structure.html

Demonstrates the use of the 'title' keyword to provide a short description for a schema.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "http://example.com/number.json#",
  "title": "Test if it is a number",
  
  "type": "number"
}
```

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

### Invalid JSON Input (Incorrect Type)

Source: https://opis.io/json-schema/2.x/definitions.html

An example of invalid JSON data where 'best_friend' is a string instead of an object, violating the schema's type definition.

```json
{
  "name": "John",
  "best_friend": "The dog"
}
```

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

### anyOf Schema Never Validates

Source: https://opis.io/json-schema/2.x/multiple-subschemas.html

Be cautious with 'anyOf' as it can lead to schemas that never validate. This example demonstrates a string schema that cannot be both a number 0 and a number 1.

```json
{
  "type": "string",
  "anyOf": [
    {"const": 0},
    {"const": 1}
  ]
}
```

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

### registerProtocolDir method

Source: https://opis.io/json-schema/2.x/php-loader.html

Registers a directory to handle URIs for a specific protocol scheme and host, similar to registerPrefix.

```APIDOC
## registerProtocolDir method

### Description

This method is similar to `registerPrefix` but is used for registering a directory to handle URIs associated with a specific protocol scheme and host.

### Signature

```php
public function registerProtocolDir(
    string $scheme,
    string $host,
    ?string $dir
): self
```

### Usage Example

```php
// Register '/path/to/dir' to handle 'http' scheme for 'example.com' host
$resolver->registerProtocolDir('http', 'example.com', '/path/to/dir');

// Files resolved from '/path/to/dir' will be prefixed with 'http://example.com/'
// For example, a file named 'data.json' in '/path/to/dir' would be accessible via 'http://example.com/data.json'
```
```

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

### 1.x Schema Loader: Separate File Loader

Source: https://opis.io/json-schema/2.x/php-migration.html

In version 1.x, schema loading from files was handled by the `Opis\JsonSchema\Loaders\File` class, which required specifying the base URI and paths.

```php
use Opis\JsonSchema\Validator;

$validator = new Validator();

$loader = new \Opis\JsonSchema\Loaders\File(
    "http://example.com/", 
    ["/path/to/schemas"]
);

$result = $validator->uriValidation(
    "some data", 
    "http://example.com/my-schema.json"
);


```

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

### Custom Single Error Output

Source: https://opis.io/json-schema/2.x/php-error-formatter.html

Example JSON output for a single validation error formatted with custom logic, showing detailed schema, error, and data information.

```json
{
  "name": {
    "schema": {
      "id": null,
      "base": "http://example.com/user.json#",
      "root": "http://example.com/user.json#",
      "draft": "2020-12",
      "path": "#/properties/name",
      "contents": {
        "type": "string",
        "minLength": 2,
        "maxLength": 100
      }
    },
    "error": {
      "keyword": "minLength",
      "args": {
        "min": 2,
        "length": 1
      },
      "message": "Minimum string length is {min}, found {length}",
      "formattedMessage": "Minimum string length is 2, found 1"
    },
    "data": {
      "type": "string",
      "value": "A",
      "fullPath": [
        "name"
      ]
    }
  },
  "age": {
    "schema": {
      "id": null,
      "base": "http://example.com/user.json#",
      "root": "http://example.com/user.json#",
      "draft": "2020-12",
      "path": "#/properties/age",
      "contents": {
        "type": "integer",
        "minimum": 18,
        "maximum": 65
      }
    },
    "error": {
      "keyword": "minimum",
      "args": {
        "min": 18
      },
      "message": "Number must be greater than or equal to {min}",
      "formattedMessage": "Number must be greater than or equal to 18"
    },
    "data": {
      "type": "integer",
      "value": 17,
      "fullPath": [
        "age"
      ]
    }
  }
}

```

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

### Registering a Custom Protocol Handler

Source: https://opis.io/json-schema/2.x/php-loader.html

Implement custom schema loading logic by registering a handler for a specific URI scheme using `registerProtocol`. The handler receives the `Uri` object and should return the schema content.

```php
use Opis\
JsonSchema\Uri;

$resolver->registerProtocol('my-proto', function (Uri $uri) {
    // ...
});
```

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

### Schema with Default Value via $ref (Won't Work)

Source: https://opis.io/json-schema/2.x/default-value.html

Illustrates a scenario where the `default` keyword is used within a definition referenced by `$ref`. This approach does not apply the default value as expected.

```json
{
    "type": "object",
    "properties": {
        "prop1": {
            "$ref": "#/$defs/str"
        }
    },
    "$defs": {
        "str": {
            "type": "string",
            "default": "test"
        }
    }
}

```

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

### JSON Schema Using a Custom Filter

Source: https://opis.io/json-schema/2.x/php-filter.html

An example of a JSON schema that utilizes the custom 'modulo' filter. This schema validates numbers based on a specified divisor and reminder.

```json
{
  "type": "number",
  "$filters": {
    "$func": "modulo",
    "$vars": {
      "divisor": 4,
      "reminder": 3
    }
  }
}

```

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

### Use Relative JSON Pointers in $vars

Source: https://opis.io/json-schema/2.x/variables.html

Reference schema data using relative JSON pointers within the $vars keyword. The example shows referencing a sibling property.

```json
{
  "$id": "http://example.com/vars-example-1#",
  "type": "object",
  "properties": {
    "prop-a": {
      "type": "string"
    },
    "prop-b": {
      "$vars": {
        "value-of-prop-a": {"$ref": "1/prop-a"},
        "some-constant": 5
      }
    }
  }
}
```

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

### oneOf Schema Never Validates

Source: https://opis.io/json-schema/2.x/multiple-subschemas.html

Similar to 'anyOf', 'oneOf' can result in schemas that never validate. This example shows a schema that cannot be both a constant 0 and an enum of [0, 1, 2].

```json
{
  "oneOf": [
    {"const": 0},
    {"enum": [0, 1, 2]}
  ]
}
```

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

### Setting Parser Options

Source: https://opis.io/json-schema/2.x/php-loader.html

Shows how to set a specific option for the parser. This is useful for customizing the validator's behavior regarding JSON Schema features.

```php
use Opis\JsonSchema\Validator;

$validator = new Validator();

// set an option
$validator->parser()->setOption($name, $value);

```

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

### Mapping Our User to Standard User Schema

Source: https://opis.io/json-schema/2.x/mappers.html

Integrates the 'standard-user.json' schema using $ref and maps 'firstName' to 'name' and provides a default for 'birthday'.

```json
{
    "allOf": [
        {
            "$ref": "standard-user.json",
            "$map": {
                "name": {"$ref": "/firstName"},
                "birthday": "1970-01-01"
            }
        }
    ]
}
```

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

### Schema: Never validates

Source: https://opis.io/json-schema/2.x/conditional-subschemas.html

Be cautious when using 'not' as it can lead to schemas that never validate. This example combines 'type: string' with 'not: { type: string }', making it impossible to satisfy.

```json
{
  "type": "string",
  "not": {
    "type": "string"
  }
}
```

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

### registerFile method

Source: https://opis.io/json-schema/2.x/php-loader.html

Registers a file as a schema with the resolver, associating it with a specific ID.

```APIDOC
## registerFile method

### Description

Use this method to register a file as a schema. You must specify the ID that will be used to reference this schema.

### Signature

```php
public function registerFile(string $id, string $file): self
```

### Usage Example

```php
$resolver->registerFile('http://example.com/schema.json', '/path/to/file.json');
```
```

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

### Global and Local Variables for URI Templates

Source: https://opis.io/json-schema/2.x/variables.html

Demonstrates how $globals and $vars keywords influence URI template variable resolution. Local $vars override global variables for specific references, while $globals set variables for subsequent schema references.

```json
{
    "type": "object",
    "properties": {
        "prop-a": {
            "$ref": "http://example.com/vendor/{VENDOR_VERSION}/a.json"
        },
        "prop-b": {
            "$ref": "http://example.com/vendor/{VENDOR_VERSION}/b.json",
            "$vars": {
                "VENDOR_VERSION": "2.0"
            }
        },
        "prop-c": {
            "$ref": "http://example.com/vendor/{VENDOR_VERSION}/c.json",
            "$vars": {
                "version": 5
            }
        },
        "prop-d": {
            "$ref": "http://example.com/vendor/{VENDOR_VERSION}/d.json",
            "$globals": {
                "VENDOR_VERSION": "3.0"
            }
        }
    }
}

```

```json
{
  "VENDOR_VERSION": "1.0"
}

```

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

### Instantiate Validator

Source: https://opis.io/json-schema/2.x/php-validator.html

Create a new instance of the Validator class. This is the basic validator for general use.

```php
use Opis\JsonSchema\Validator;

$validator = new Validator();

```
Tokens:
Raw