A robust JSON decoder/encoder with support for schema validation.

Bernhard Schussek

Last update: Dec 21, 2022

Related tags

API json

Overview

Webmozart JSON

Latest release: 1.2.2

A robust wrapper for json_encode()/json_decode() that normalizes their behavior across PHP versions, throws meaningful exceptions and supports schema validation by default.

Installation

Use Composer to install the package:

$ composer require webmozart/json

Encoding

Use the JsonEncoder to encode data as JSON:

use Webmozart\Json\JsonEncoder;

$encoder = new JsonEncoder();

// Store JSON in string
$string = $encoder->encode($data);

// Store JSON in file
$encoder->encodeFile($data, '/path/to/file.json');

By default, the JSON schema stored in the $schema property of the JSON document is used to validate the file. You can also pass the path to the schema in the last optional argument of both methods:

use Webmozart\Json\ValidationFailedException;

try {
    $string = $encoder->encode($data, '/path/to/schema.json');
} catch (ValidationFailedException $e) {
    // data did not match schema 
}

Decoding

Use the JsonDecoder to decode a JSON string/file:

use Webmozart\Json\JsonDecoder;

$decoder = new JsonDecoder();

// Read JSON string
$data = $decoder->decode($string);

// Read JSON file
$data = $decoder->decodeFile('/path/to/file.json');

Like JsonEncoder, the decoder accepts the path to a JSON schema in the last optional argument of its methods:

use Webmozart\Json\ValidationFailedException;

try {
    $data = $decoder->decodeFile('/path/to/file.json', '/path/to/schema.json');
} catch (ValidationFailedException $e) {
    // data did not match schema 
}

Validation

Sometimes it is necessary to separate the steps of encoding/decoding JSON data and validating it against a schema. In this case, you can omit the schema argument during encoding/decoding and use the JsonValidator to validate the data manually later on:

use Webmozart\Json\JsonDecoder;
use Webmozart\Json\JsonValidator;
use Webmozart\Json\ValidationFailedException;

$decoder = new JsonDecoder();
$validator = new JsonValidator();

$data = $decoder->decodeFile('/path/to/file.json');

// process $data...

$errors = $validator->validate($data, '/path/to/schema.json');

if (count($errors) > 0) {
    // data did not match schema 
}

Note: This does not work if you use the $schema property to set the schema (see next section). If that property is set, the schema is always used for validation during encoding and decoding.

Schemas

You are encouraged to store the schema of your JSON documents in the $schema property:

{
    "$schema": "http://example.org/schemas/1.0/schema"
}

The utilities in this package will load the schema from the URL and use it for validating the document. Obviously, this has a hit on performance and depends on the availability of the server and an internet connection. Hence you are encouraged to ship the schema with your package. Use the LocalUriRetriever to map the URL to your local schema file:

$uriRetriever = new UriRetriever();
$uriRetriever->setUriRetriever(new LocalUriRetriever(
    // base directory
    __DIR__.'/../res/schemas',
    // list of schema mappings
    array(
        'http://example.org/schemas/1.0/schema' => 'schema-1.0.json',
    )
));

$validator = new JsonValidator(null, $uriRetriever);
$encoder = new JsonEncoder($validator);
$decoder = new JsonDecoder($validator);

// ...

Conversion

You can implement JsonConverter to encapsulate the conversion of objects from and to JSON structures in a single class:

use stdClass;
use Webmozart\Json\Conversion\JsonConverter;

class ConfigFileJsonConverter implements JsonConverter
{
    const SCHEMA = 'http://example.org/schemas/1.0/schema';
    
    public function toJson($configFile, array $options = array())
    {
        $jsonData = new stdClass();
        $jsonData->{'$schema'} = self::SCHEMA;
         
        if (null !== $configFile->getApplicationName()) {
            $jsonData->application = $configFile->getApplicationName();
        }
        
        // ...
        
        return $jsonData;
    }
    
    public function fromJson($jsonData, array $options = array())
    {
        $configFile = new ConfigFile();
        
        if (isset($jsonData->application)) {
            $configFile->setApplicationName($jsonData->application);
        }
        
        // ...
        
        return $configFile;
    }
}

Loading and dumping ConfigFile objects is very simple now:

$converter = new ConfigFileJsonConverter();

// Load config.json as ConfigFile object
$jsonData = $decoder->decodeFile('/path/to/config.json');
$configFile = $converter->fromJson($jsonData);

// Save ConfigFile object as config.json
$jsonData = $converter->toJson($configFile);
$encoder->encodeFile($jsonData, '/path/to/config.json');

You can automate the schema validation of your ConfigFile by wrapping the converter in a ValidatingConverter:

use Webmozart\Json\Validation\ValidatingConverter;

$converter = new ValidatingConverter(new ConfigFileJsonConverter());

You can also validate against an explicit schema by passing the schema to the ValidatingConverter:

use Webmozart\Json\Validation\ValidatingConverter;

$converter = new ValidatingConverter(
    new ConfigFileJsonConverter(),
    __DIR__.'/../res/schema/config-schema.json'
);

Versioning and Migration

When you continuously develop an application, you will enter the situation that you need to change your JSON schemas. Updating JSON files to match their changed schemas can be challenging and time consuming. This package supports a versioning mechanism to automate this migration.

Imagine config.json files in three different versions: 1.0, 2.0 and 3.0. The name of a key changed between those versions:

config.json (version 1.0)

{
    "$schema": "http://example.org/schemas/1.0/schema",
    "application": "Hello world!"
}

config.json (version 2.0)

{
    "$schema": "http://example.org/schemas/2.0/schema",
    "application.name": "Hello world!"
}

config.json (version 3.0)

{
    "$schema": "http://example.org/schemas/3.0/schema",
    "application": {
        "name": "Hello world!"
    }
}

You can support files in any of these versions by implementing:

A converter compatible with the latest version (e.g. 3.0)
Migrations that migrate older versions to newer versions (e.g. 1.0 to 2.0 and 2.0 to 3.0.

Let's look at an example of a ConfigFileJsonConverter for version 3.0:

use stdClass;
use Webmozart\Json\Conversion\JsonConverter;

class ConfigFileJsonConverter implements JsonConverter
{
    const SCHEMA = 'http://example.org/schemas/3.0/schema';
    
    public function toJson($configFile, array $options = array())
    {
        $jsonData = new stdClass();
        $jsonData->{'$schema'} = self::SCHEMA;
         
        if (null !== $configFile->getApplicationName()) {
            $jsonData->application = new stdClass();
            $jsonData->application->name = $configFile->getApplicationName();
        }
        
        // ...
        
        return $jsonData;
    }
    
    public function fromJson($jsonData, array $options = array())
    {
        $configFile = new ConfigFile();
        
        if (isset($jsonData->application->name)) {
            $configFile->setApplicationName($jsonData->application->name);
        }
        
        // ...
        
        return $configFile;
    }
}

This converter can be used as described in the previous section. However, it can only be used with config.json files in version 3.0.

We can add support for older files by implementing the JsonMigration interface. This interface contains four methods:

getSourceVersion(): returns the source version of the migration
getTargetVersion(): returns the target version of the migration
up(stdClass $jsonData): migrates from the source to the target version
down(stdClass $jsonData): migrates from the target to the source version

use Webmozart\Json\Migration\JsonMigration;

class ConfigFileJson20To30Migration implements JsonMigration
{
    const SOURCE_SCHEMA = 'http://example.org/schemas/2.0/schema';
    
    const TARGET_SCHEMA = 'http://example.org/schemas/3.0/schema';
    
    public function getSourceVersion()
    {
        return '2.0';
    }
    
    public function getTargetVersion()
    {
        return '3.0';
    }
    
    public function up(stdClass $jsonData)
    {
        $jsonData->{'$schema'} = self::TARGET_SCHEMA;
        
        if (isset($jsonData->{'application.name'})) {
            $jsonData->application = new stdClass();
            $jsonData->application->name = $jsonData->{'application.name'};
            
            unset($jsonData->{'application.name'});
        )
    }
    
    public function down(stdClass $jsonData)
    {
        $jsonData->{'$schema'} = self::SOURCE_SCHEMA;
        
        if (isset($jsonData->application->name)) {
            $jsonData->{'application.name'} = $jsonData->application->name;
            
            unset($jsonData->application);
        )
    }
}

With a list of such migrations, we can create a MigratingConverter that decorates our ConfigFileJsonConverter:

use Webmozart\Json\Migration\MigratingConverter;
use Webmozart\Json\Migration\MigrationManager;

// Written for version 3.0
$converter = new ConfigFileJsonConverter();

// Support for older versions. The order of migrations does not matter.
$migrationManager = new MigrationManager(array(
    new ConfigFileJson10To20Migration(),
    new ConfigFileJson20To30Migration(),
));

// Decorate the converter
$converter = new MigratingConverter($converter, $migrationManager);

The resulting converter is able to load and dump JSON files in any of the versions 1.0, 2.0 and 3.0.

// Loads a file in version 1.0, 2.0 or 3.0
$jsonData = $decoder->decodeFile('/path/to/config.json');
$configFile = $converter->fromJson($jsonData);

// Writes the file in the latest version by default (3.0)
$jsonData = $converter->toJson($configFile);
$encoder->encodeFile($jsonData, '/path/to/config.json');

// Writes the file in a specific version
$jsonData = $converter->toJson($configFile, array(
    'targetVersion' => '2.0',
));
$encoder->encodeFile($jsonData, '/path/to/config.json');

Validation of Different Versions

If you want to add schema validation, wrap your encoder into a ValidatingConverter. You can wrap both the inner and the outer converter to make sure that both the JSON before and after running the migrations complies to the corresponding schemas.

// Written for version 3.0
$converter = new ConfigFileJsonConverter();

// Decorate to validate against the schema at version 3.0
$converter = new ValidatingConverter($converter);

// Decorate to support different versions
$converter = new MigratingConverter($converter, $migrationManager);

// Decorate to validate against the old schema
$converter = new ValidatingConverter($converter);

If you store the version in a version field (see below) and want to use a custom schema depending on that version, you can pass schema paths or closures for resolving the schema paths:

// Written for version 3.0
$converter = new ConfigFileJsonConverter();

// Decorate to validate against the schema at version 3.0
$converter = new ValidatingConverter($converter, __DIR__.'/../res/schema/config-schema-3.0.json');

// Decorate to support different versions
$converter = new MigratingConverter($converter, $migrationManager);

// Decorate to validate against the old schema
$converter = new ValidatingConverter($converter, function ($jsonData) {
    return __DIR__.'/../res/schema/config-schema-'.$jsonData->version.'.json'
});

Using Custom Schema Versioning

By default, the version of the schema is stored in the schema name:

{
    "$schema": "http://example.com/schemas/1.0/my-schema"
}

The version must be enclosed by slashes. Appending the version to the schema, for example, won't work:

{
    "$schema": "http://example.com/schemas/my-schema-1.0"
}

You can however customize the format of the schema URI by creating a SchemaUriVersioner with a custom regular expression:

use Webmozart\Json\Versioning\SchemaUriVersioner;

$versioner = new SchemaUriVersioner('~(?<=-)\d+\.\d+(?=$)~');

$migrationManager = new MigrationManager(array(
    // migrations...
), $versioner);

// ...

The regular expression must match the version only. Make sure to wrap characters before and after the version in look-around assertions ((?<=...), (?=...)).

Storing the Version in a Field

Instead of storing the version in the schema URI, you could also store it in a separate field. For example, the field "version":

{
    "version": "1.0"
}

This use case is supported by the VersionFieldVersioner class:

use Webmozart\Json\Versioning\VersionFieldVersioner;

$versioner = new VersionFieldVersioner();

$migrationManager = new MigrationManager(array(
    // migrations...
), $versioner);

// ...

The constructor of VersionFieldVersioner optionally accepts a custom field name used to store the version. The default field name is "version".

Authors

Bernhard Schussek a.k.a. @webmozart
The Community Contributors

Contribute

Contributions to the package are always welcome!

Report any bugs or issues you find on the issue tracker.
You can grab the source code at the package's Git repository.

Support

If you are having problems, send a mail to [email protected] or shout out to @webmozart on Twitter.

License

All contents of this package are licensed under the MIT license.

Comments

Is the RefResolver intentionally not being used?

Thanks for this library. I'm using it and now that I'm trying to use references in schemas I'm asking myself whether you not resolve references on purpose? See this gist for an example. Without doing the reference resolution the schema contains

    "properties": {
        "billing_address": {
            "$ref": "#/definitions/address"
        },
        "shipping_address": {
            "$ref": "#/definitions/address"
        }
    },

instead of

"properties": {
        "billing_address": {
            "type": "object",
            "properties": {
                "street_address": {
                    "type": "string"
                },
                "city": {
                    "type": "string"
                },
                "state": {
                    "type": "string"
                }
            },
            "required": [
                "street_address",
                "city",
                "state"
            ],
            "id": "file:///srv/www/json-schema/schema-address.json#/definitions/address"
        },
        "shipping_address": {
            "type": "object",
            "properties": {
                "street_address": {
                    "type": "string"
                },
                "city": {
                    "type": "string"
                },
                "state": {
                    "type": "string"
                }
            },
            "required": [
                "street_address",
                "city",
                "state"
            ],
            "id": "file:///srv/www/json-schema/schema-address.json#/definitions/address"
        }
    }

Apart from the underlying library not supporting all cases of definitions and $ref usage I just wanted to make sure whether you're deviating intentionally from the README example of justinrainbow/json-schema.

opened by graste 8

Working with empty keys in JSON
Hi,

I have empty keys in my json that represent empty values in dropdowns. When I use native json_decode, empty keys are transformed to _empty_ string. This is a known PHP bug: https://bugs.php.net/bug.php?id=46600

So the following json decoded and encoded again is not the same as original:

$json = '{"test": {"": "foo"}}'; var_dump(json_encode(json_decode($json))); // "{"test":{"_empty_":"foo"}}"

Notice an _empty_ key instead of '' key.

The same behaviour is when I use this package:

$encoder = new JsonEncoder(); $decoder = new JsonDecoder(); $decoded = $decoder->decode('{"test": {"": "foo"}}'); dump($decoded); dump($encoder->encode($decoded)); // output {#1316 +"test": {#1317 +"_empty_": "foo" } } "{"test":{"_empty_":"foo"}}"

Do you have any recommendations on how to avoid this? I cant use assoc = true because in my json there are many keys with empty objects that are converted back as arrays when you use assoc = true

For now I use an ugly solution with replacing all _empty_ keys with empty strings:

private function jsonEncode($content) { $jsonString = json_encode($content, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); $fixedJsonString = str_replace('"_empty_":', '"":', $jsonString); return $fixedJsonString; }
opened by maks-rafalko 5
Support justinrainbow/json-schema 2.x

Follow up for #18, which supports both major versions.

The tests fail with 1.x, but these failures seem to have already existed. (The tests seem to now pass with 2.x.)

opened by thewilkybarkid 3
composer installs outdated package

Hello!

For some reason, composer require webmozart/json yields outdated package from Jan 14, which does not contain none of VersionFieldVersioner, SchemaUriVersioner, MigrationManager, MigratingConverter, JsonMigration, JsonConverter, ValidatingConverter, etc.

Please advise asap.

opened by skvskv 3
Release tag does not include complete library.

I think most of your library is missing from the release. See release tag 1.2.2 here : https://github.com/webmozart/json/tree/a1fb3da904b8364e3db47eed68f76bfb6cd0031a/src

composer require webmozart/json gives "webmozart/json": "^1.2", installs version 1.2.2

Comparing repository at tag 1.2.2 with master reveals obvious lack of code : https://github.com/webmozart/json/tree/master/src

opened by tomgud 2
RFC use develop branch for next changes

Hey @webmozart ,

I was looking for a way to handle json schema $ref locally and was happy that your package provides a nice mechanism: https://github.com/webmozart/json#schemas

We have the latest version installed 1.2.2 but the JsonValidator looks different in this version. So I was confused. Wouldn't it be better to work on upcoming feature in a develop branch so that the README in the master branch reflects the latest released version instead of the next?

opened by codeliner 1
SCIM

This is not a bug report bug a general question about this library, validation and SCIM (https://tools.ietf.org/html/rfc7643).

Do you know if it is possible to use schemas described in the RFC7643 to validate SCIM resources using that library?

opened by Spomky 1
Use same RefResolver

In #20 I had made a change to use the same RefResolver rather than creating a new instance each time (see https://github.com/justinrainbow/json-schema/pull/290). The brings it back in to avoid memory problems.

opened by thewilkybarkid 1
Version Bump for new json Release
I've updated the composer dependencies of this project and bumped the PHP minimum Version to 7.1, but there are a questions about failing tests and how I should handle them.

Some tests are referring to fixtures of an external source, webmozart.io. Were those removed? I currently skipped those in my branch.

There are two other tests where I have to find the reason why they fail, so maybe I'll come back to them later in case I've questions about them.

I also have to see how the travis build will result and work further on making this project work with newer dependencies.
opened by SenseException 0
Added support for empty properties (fixes #19)
This PR adds support for empty properties before PHP 7.1. Before that version, empty properties are decoded as _empty_:

$decoded = $decoder->decode('{"":"Foobar"}'); var_dump($decoded); // stdClass('_empty_' => 'Foobar')

However, when encoding the same object again, PHP does not convert the _empty_ property back:

var_dump($encoder->encode($decoded)); // {"_empty_":"Foobar"}

This is problematic if you want to load and write files with empty keys on a lower version than PHP 7.1.

This PR fixes the JsonEncoder below 7.1 to convert _empty_ properties to "", hence the following condition holds on all supported PHP versions:

'{"":"Foobar"}' === $encoder->encode($decoder->decode('{"":"Foobar"}'));
opened by webmozart 0
use Puli to load json schemas in JsonValidator

res/meta-schema.json could be mapped to /webmozart/json/meta-schema.json and JsonValidator::loadSchema should load Puli ressources

note: I have no idea how it could be done without introducing a BC break :/

opened by mathroc 0
[Help/Contributor needed] Major release & refactoring for PHP8 support
PHPUnit ^9.3 supports PHP 7.3, 7.4 and 8.0

PHPUnit ^8.5.12 supports PHP >=7.2

I can't figure how to add PHP 8 support alongside PHP 5 | 7.(0-2)

The idea is to make a new major release only for people using PHP >=7.3 by using PHPUnit ^9.3 But I imagine we can also use PHPUnit 8.5.12 for 7.2, 7.3, 7.4 and 8.0

People still using PHP 5.x should stay on the v1.x release

Changes

added return type on every test

replaced string FQCN in tests with import

refactored classes using the old validator to use the JsonSchema validator

removed some tests against PHP < 7.3

removed src/InvalidSchemaException.php

removed src/JsonValidator.php

replaced JsonValidator with JsonSchema\Validator

Need check

JsonSchema provides its own implementation for checking validation against a given schema. It also raises an exception called InvalidSchemaException

InvalidSchemaException seems not to be raised by default with JsonSchema\Validator. I think we must explicitly use the Constraint::CHECK_MODE_EXCEPTIONS for that (https://github.com/justinrainbow/json-schema#configuration-options)

I've removed tests against given invalid schema string path as it does not raise an exception on the third party validator by default

A question needs to be answered: who has the responsibility to convert a given string schema path to a compliant object for JsonSchema\Validator? I've dropped that responsibility in the package for now. You can check the example bellow from the JsonSchema README

// Validate $validator = new JsonSchema\Validator; $validator->validate($data, (object)['$ref' => 'file://' . realpath('schema.json')]);

https://github.com/justinrainbow/json-schema#basic-usage

Note

I stop working on this pull request.

I wanted to add support for PHP 8 as I've created an issue which has remained unanswered.

The thing is that this library is using a very old release of JsonSchema and it has not been upgraded since 2016. JsonSchema is now at its fifth major release.

Feel free to progress this work. I'm done for now and I'll stop be using this library in my projects.
opened by samijnih 1
The justinrainbow/json-schema package version is out of date

Currently, the library requires version ^1.6 of justinrainbow/json-schema. The current stable version is 5.2.0: https://packagist.org/packages/justinrainbow/json-schema

opened by fireproofsocks 1
Problem with big int
Following code:

$json = '{"int_overflow":9223372036854775807}'; $decoder = new JsonDecoder(); $decode = $decoder->decode($json);

Throws exception: json_decode(): integer overflow detected. This should be translate from a big int to the string value.
opened by piotrooo 1
Always validate against $schema property

From the README:

By default, the JSON schema stored in the $schema property of the JSON document is used to validate the file.

However, it doesn't look like this is actually happening. This PR fixes that.

opened by CupOfTea696 0

Releases(1.2.2)

1.2.2(Jan 14, 2016)
fixed loading of schemas from PHARs

Source code(tar.gz)
Source code(zip)
1.2.1(Jan 14, 2016)
bumped justinrainbow/json-schema to 1.6 to fix "pattern-properties" with slashes

Source code(tar.gz)
Source code(zip)
1.2.0(Jan 2, 2016)
added support for $ref in schemas

Source code(tar.gz)
Source code(zip)
1.1.1(Dec 28, 2015)
fixed PHP 7 compatibility

Source code(tar.gz)
Source code(zip)
1.1.0(Dec 11, 2015)
added IOException and better error handling in JsonEncoder::encodeFile() and JsonDecoder::decodeFile()

JsonEncoder::encodeFile() now creates missing directories on demand

JsonEncoder now throws an exception on all PHP versions when binary values are passed

added support for disabled slash escaping on PHP below 5.4

Source code(tar.gz)
Source code(zip)
1.0.2(Aug 11, 2015)
fixed decoding of 'null'

Source code(tar.gz)
Source code(zip)
1.0.1(Jun 4, 2015)
fixed detection of the JSONC library in JsonDecoder::decodeJson()

Source code(tar.gz)
Source code(zip)
1.0.0(Mar 19, 2015)
flipped $data and $file arguments of JsonEncoder::encodeFile()

Source code(tar.gz)
Source code(zip)
1.0.0-beta(Jan 21, 2015)
renamed SchemaException to InvalidSchemaException

changed JsonValidator::validate() to return the discovered errors instead of throwing an exception

Source code(tar.gz)
Source code(zip)
1.0.0-alpha1(Jan 21, 2015)

Source code(tar.gz)
Source code(zip)

Owner

Bernhard Schussek

GitHub

Like FormRequests, but for validating against a json-schema

JSON Schema Request Laravels Form Request Validation for JSON Schema documents Installation composer require wt-health/laravel-json-schema-request Us

1 Feb 3, 2022

EXPERIMENTAL plugin extending WPGraphQL to support querying (Gutenberg) Blocks as data, using Server Side Block registries to map Blocks to the GraphQL Schema.

WPGraphQL Block Editor This is an experimental plugin to work toward compatiblity between the WordPress Gutenberg Block Editor and WPGraphQL, based on

29 Nov 18, 2022

Tukio is a complete and robust implementation of the PSR-14 Event Dispatcher specification

Tukio is a complete and robust implementation of the PSR-14 Event Dispatcher specification. It supports normal and debug Event Dispatchers, both runtime and compiled Providers, complex ordering of Listeners, and attribute-based registration on PHP 8.

70 Dec 19, 2022

🍞🧑‍🍳 An on-the-fly GraphQL Schema generator from Eloquent models for Laravel.

An on-the-fly GraphQL Schema generator from Eloquent models for Laravel. Installation Quickstart Model schemas Installation This package requires PHP

100 Oct 16, 2022

Code shared by the schema packages

2 Nov 4, 2022

Quickly and easily expose Doctrine entities as REST resource endpoints with the use of simple configuration with annotations, yaml, json or a PHP array.

Drest Dress up doctrine entities and expose them as REST resources This library allows you to quickly annotate your doctrine entities into restful res