Opis JSON Schema: a PHP validator for every JSON Schema draft

One implementation, four drafts

Opis JSON Schema is a PHP implementation of the JSON Schema standard, and the key feature is stated first in the list, which is support for all keywords from all drafts, from draft-2020-12 down to draft-06. The library covers draft-2020-12, draft-2019-09, draft-07 and draft-06. That range matters more than it sounds, because the drafts are not just versions of the same document. A schema written for draft-07 does not necessarily behave the same way under a draft-2020-12 validator, in particular around how references and vocabularies resolve, and a large body of existing schemas in the wild targets the older drafts. Covering all of them in one implementation means a codebase that has accumulated a decade of schemas does not have to decide which validator it trusts. The stated purpose is validating all sorts of JSON documents, whether they are configuration files or a set of data sent to a RESTful API endpoint, which is the two cases that make up most real validation work.

The extensions that make it more than a validator

The feature list is where this library separates itself from a minimal implementation, and the extensions are all keyword based, which means they live inside the schema document rather than in your code. The `$error` keyword supports custom errors inside the schema, so the failure message is written next to the rule that failed rather than assembled by hand afterwards. The `$filters` keyword supports custom PHP filters, which is how a schema can call into your own code to decide whether a value is acceptable. The `$map` keyword provides advanced schema reuse, and slots give intuitive schema composition, so a shared definition can be parameterised and reused without string concatenation. There is support for absolute and relative JSON pointers, for URI templates, for the `$data` keyword, which lets a schema refer to values in the instance being validated, and for casting, plus custom formats and custom media types. The `$data` keyword and the filters are the two that change what a schema can express, because both let the schema depend on runtime context rather than only on the value in front of it.

Installing it and the PHP version it needs

The library is on Packagist and installs with Composer:

composer require opis/json-schema

Or you can reference it directly in your `composer.json` file as a dependency:

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

The requirement is PHP ^7.4 or ^8.0, which is the practical constraint for adoption, since supporting both the 7.x and 8.x lines is what lets the same constraint sit in an application that is mid migration. The repository is a small, conventional PHP package layout, with a `src/` directory, a `tests/` directory, a `composer.json`, a `phpunit.xml`, an `autoload.php` file, a `LICENSE` and a `NOTICE` file, and a `SECURITY.md`. The presence of a NOTICE file and a separate Apache-2.0 licence file is the shape you would expect from a project that is used in a lot of commercial codebases, since the NOTICE obligation is one that Apache-2.0 users have to carry forward.

The documentation covers the standard as well as the library

The README points to the full documentation and makes a distinction that is helpful in practice: the project provides documentation for the JSON Schema standard itself as well as for the library's own API. That is not vanity. The keywords in the standard have changed behaviour between drafts, and the reference material for the standard is the thing you actually need when a schema behaves in a way you did not expect, whether that is because the schema is wrong or because the implementation is. The library-specific pages are linked individually for each extension, with separate pages for errors, filters, mappers, slots, pointers, URI templates, the data keyword, the casting pragma, custom formats and custom media types. The documentation site is opis.io/json-schema, and the topics on the repository list json-schema, json-pointer, opis and php, which matches the scope: a validator, a pointer implementation and the language binding.

The version story, and the v1 line

The recent tags show two release lines running at once. Version 2.6.0 was published on 2025-10-17 and 2.5.0 on 2025-10-08, nine days apart, and then there is 1.2.0 from 2025-03-05, whose release title is the giveaway, support for PHP 8.4 for the v1 line. So the v2 series is where new work is landing, and the v1 series is being kept alive for the PHP versions it targets, which is a common and sensible pattern for a library with a wide installed base. The last push was on 2026-04-30, which is after the last tag, so the working tree has moved on from 2.6.0 without a new release. The Composer constraint in the README, `^2.6`, puts the floor at the 2.6 series, so an installation today gets 2.6.0 or a later 2.x. The homepage is opis.io/json-schema, and the project is not archived.

Where this is the wrong choice

The limits are mostly about fit rather than quality. First, it is a PHP library. If the code that receives the JSON is not PHP, a PHP validator in the request path is an architectural decision you have to justify, and the project does not describe a port to another language, so you would be calling a service or rewriting the validation yourself. Second, the extension keywords are not portable. A schema using `$filters` is a schema that only this library can evaluate, since the filters are PHP callables, and if you ever need to validate the same documents elsewhere, those schemas become a liability. The same applies to `$data` and to the custom format and media type handling, though those are narrower. Third, the breadth of draft support cuts both ways. A validator that accepts draft-06 through draft-2020-12 has to make choices about which behaviour applies when a schema is ambiguous, and a schema author working from a newer draft may hit a keyword that behaved differently in the draft they copied from. Fourth, the size of the dependency for a simple job. If you need to check that a config file has a string field, a full validator with mappers and slots and filters is more than the task requires. And fifth, the maintenance question. The v1 line exists to support older PHP, which is a good sign for stability but also a sign that the project is carrying compatibility for a range of runtimes, and a consumer that only needs the current PHP has a narrower and simpler choice available.

Editorial conclusion

Opis JSON Schema fits a PHP team that has to validate untrusted JSON against a schema, especially one that needs the older drafts, the $data keyword or PHP specific formats, since the same library covers all of those in one implementation. It is the wrong choice if you need validation in a runtime where PHP is not present, since this is a PHP library with no stated port, and the wrong choice if you want the absolute minimum overhead for a trivial schema, since it is a substantial dependency for a simple check. Before you adopt it, read the documentation for the standard itself as well as the library API, and check which draft your schemas actually use, because the keyword behaviour differs between drafts. The last push was on 2026-04-30, version 2.6.0 was released on 2025-10-17, and the library is Apache-2.0 licensed.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. opis/json-schema on GitHub
3. Project website
4. README
5. Releases