PHP RFC: JSON Schema validation support

• Version: 0.1
• Date: 2025-06-15
• Author: Jakub Zelenka, bukka@php.net
• Status: Draft

The json extension does not offer any way of structural validation of the content except basic syntax checking. Being able to validate the actual structure is very useful in many ways and it has been requested many times.

The JSON Schema became a primary method of validation the JSON and has been widely adopted. As such PHP would benefit from having that support in JSON extenions.

The proposal is to add support JSON Schema to JSON extension. Specifically, it adds support to json_decode and json_validate. This is done as an additional argument that accepts schema object. The object can be created from string. The error handling is consistent with the current handling.

The proposal introduces a new class JsonSchema that can be created only using static method createFromString. It also introduces a new exception class JsonSchemaException that is a subclass of JsonException. The API stub is following:

<?php
class JsonSchemaException extends JsonException
{
}
 
/** @not-serializable */
class JsonSchema
{
    private final function __construct() {}
 
    public static function createFromString(string $source): JsonSchema {}
}
 
// Addition of $schema paramater
function json_decode(string $json, ?bool $associative = null, int $depth = 512, int $flags = 0, ?JsonSchema $schema = null): mixed {}
 
// Addition of $schema paramater
function json_validate(string $json, int $depth = 512, int $flags = 0, ?JsonSchema $schema = null): bool {}
?>

In addition, a set of new error constants is introduced. These codes are either used as exception codes or global error codes. This means it follows the current error handling in the JSON extension.

None

PHP 8.5

The significant effort to develop the whole library for JSON Schema wasn't just to introduce verification. The main motivation was about what this might allow, primarily the ability to map JSON data to specific PHP classes and the ability to do early parsing termination, thus potentially eliminating hash DoS attacks. Specifically, the following features might be considered:

• Support for default draft selection to allow schemas without the $schema tag (technically not compliant to the spec)
• Complete support for all drafts
• Early validation failure if it is certain that an instance will be invalid (this is actually not that simple due to composition, but it is doable)
• Special new schema keyword to specify mapping class for objects and subsequent mapping into them (native hydration)
• New creation functions like createFromArray and possibly createFromClass (possibility to automatically generate schema from class and attributes)
• Better error reporting (location of the error)
• Optional validation of some formats
• Exposing JSON pointer to user space (e.g., JsonPointer class)

The above list contains more ideas that might be proposed, but each of them will, of course, require a separate RFC. There are more things that can be done as well. In addition to the schema-specific parts, the plan is to also look into the introduction of a new SIMD parser that would live in jso and could be used by the json extension. That could result in significant performance gains.

As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted.

The vote started on 2025-07-DD at mm:hh UTC and ends on 2015-07-DD at mm:hh UTC.

A working implementation has been added to jsond and can be seen at https://github.com/bukka/php-jsond/tree/next. The jsond extension is almost the same as the json extension with some minor changes and different naming. This means that pretty much the same implementation can be added to the json extension.

The actual schema integration is done using my jso library that can be found at https://github.com/bukka/jso. This is an independent library initially developed for testing the json parser before it was migrated to jsond and later became the current implementation of the json extension. The development of JSON schema validation started a few years ago and has stabilized over time. There is still ongoing development to support more drafts. The current status is almost complete draft 4 and 6 support. Draft 7 support is coming soon. Other drafts might be available before the PHP RC1 version. The reason the development is separated is the possibility of introducing unit tests and specifically tailored integration tests. It is also much easier to debug and verify issues as well as experiment with new features.

The library is bundled and there is a sync script to synchronize the jso additions. The library allows specific virtual header overrides for virtual types. This means that it can effectively wrap internal PHP types and does not need to do extra copying to process the verified instances. The plan is to synchronize the release cycle of the library so it has stable branches that can be tracked by PHP branches.

After the project is implemented, this section will contain

1. the version(s) it was merged to
2. a link to the git commit(s)