PHP使用JSON Schema进行JSON数据验证和类型检查

什么是JSON Schema？

JSON Schema是一个用于描述和验证JSON数据结构的规范。JSON Schema可以验证JSON数据是否符合指定的模式、类型和约束条件，同时还可以提供数据文档化的作用。

JSON Schema的结构

JSON Schema结构分为三个部分JSON Schema结构分为三个部分：

关键字

这是JSON Schema中最重要的部分，它定义了用于数据验证的规则和条件，例如：required，type，properties，minimum等。可以在规范中查看完整的关键字列表。

架构实例

架构实例是一个JSON文件或对象，它描述了要验证的数据结构，包括数据类型、属性名称、数值范围等。

元数据

元数据是用于描述JSON Schema本身的数据，例如：title，description，id等。这些元数据不会被用于验证JSON数据，但是它们对于理解Schema非常重要。

使用 JSON Schema

justinrainbow/json-schema 是一个PHP实现，用于根据给定的 Schema 验证 JSON 结构，支持草案3或草案4的 Schemas。可能不支持较新草稿的功能。请参阅所有版本的表格，以获得所有现有草稿的概述。

安装

composer require justinrainbow/json-schema

基本用法

<?php

$data = json_decode(file_get_contents(\\\'data.json\\\'));

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

if ($validator->isValid()) {
    echo \\\"The supplied JSON validates against the schema.\\\\n\\\";
} else {
    echo \\\"JSON does not validate. Violations:\\\\n\\\";
    foreach ($validator->getErrors() as $error) {
        printf(\\\"[%s] %s\\\\n\\\", $error[\\\'property\\\'], $error[\\\'message\\\']);
    }
}

类型强制

如果你正在验证通过HTTP传递给你的应用程序的数据，你可以将字符串和布尔值转换为你的模式定义的预期类型：

<?php

use JsonSchema\\\\SchemaStorage;
use JsonSchema\\\\Validator;
use JsonSchema\\\\Constraints\\\\Factory;
use JsonSchema\\\\Constraints\\\\Constraint;

$request = (object)[
    \\\'processRefund\\\'=>\\\"true\\\",
    \\\'refundAmount\\\'=>\\\"17\\\"
];

$validator->validate(
    $request, (object) [
    \\\"type\\\"=>\\\"object\\\",
        \\\"properties\\\"=>(object)[
            \\\"processRefund\\\"=>(object)[
                \\\"type\\\"=>\\\"boolean\\\"
            ],
            \\\"refundAmount\\\"=>(object)[
                \\\"type\\\"=>\\\"number\\\"
            ]
        ]
    ],
    Constraint::CHECK_MODE_COERCE_TYPES
); // validates!

is_bool($request->processRefund); // true
is_int($request->refundAmount); // true

也可以使用速记方法：

$validator->coerce($request, $schema);
// equivalent to $validator->validate($data, $schema, Constraint::CHECK_MODE_COERCE_TYPES);

默认值

如果您的架构包含默认值，则可以在验证期间自动应用这些值：

<?php

use JsonSchema\\\\Validator;
use JsonSchema\\\\Constraints\\\\Constraint;

$request = (object)[
    \\\'refundAmount\\\'=>17
];

$validator = new Validator();

$validator->validate(
    $request,
    (object)[
        \\\"type\\\"=>\\\"object\\\",
        \\\"properties\\\"=>(object)[
            \\\"processRefund\\\"=>(object)[
                \\\"type\\\"=>\\\"boolean\\\",
                \\\"default\\\"=>true
            ]
        ]
    ],
    Constraint::CHECK_MODE_APPLY_DEFAULTS
); //validates, and sets defaults for missing properties

is_bool($request->processRefund); // true
$request->processRefund; // true

使用内联引用

<?php

use JsonSchema\\\\SchemaStorage;
use JsonSchema\\\\Validator;
use JsonSchema\\\\Constraints\\\\Factory;

$jsonSchema = <<<\\\'JSON\\\'
{
    \\\"type\\\": \\\"object\\\",
    \\\"properties\\\": {
        \\\"data\\\": {
            \\\"oneOf\\\": [
                { \\\"$ref\\\": \\\"#/definitions/integerData\\\" },
                { \\\"$ref\\\": \\\"#/definitions/stringData\\\" }
            ]
        }
    },
    \\\"required\\\": [\\\"data\\\"],
    \\\"definitions\\\": {
        \\\"integerData\\\" : {
            \\\"type\\\": \\\"integer\\\",
            \\\"minimum\\\" : 0
        },
        \\\"stringData\\\" : {
            \\\"type\\\": \\\"string\\\"
        }
    }
}
JSON;

// Schema must be decoded before it can be used for validation
$jsonSchemaObject = json_decode($jsonSchema);

// The SchemaStorage can resolve references, loading additional schemas from file as needed, etc.
$schemaStorage = new SchemaStorage();

// This does two things:
// 1) Mutates $jsonSchemaObject to normalize the references (to file://mySchema#/definitions/integerData, etc)
// 2) Tells $schemaStorage that references to file://mySchema... should be resolved by looking in $jsonSchemaObject
$schemaStorage->addSchema(\\\'file://mySchema\\\', $jsonSchemaObject);

// Provide $schemaStorage to the Validator so that references can be resolved during validation
$jsonValidator = new Validator(new Factory($schemaStorage));

// JSON must be decoded before it can be validated
$jsonToValidateObject = json_decode(\\\'{\\\"data\\\":123}\\\');

// Do validation (use isValid() and getErrors() to check the result)
$jsonValidator->validate($jsonToValidateObject, $jsonSchemaObject);

配置选项

有许多标志可用于改变验证器的行为。这些可以作为第三个参数传递给Validator::validate()，或者如果您希望在多个validate()调用中持久化它们，则可以作为第三个参数提供给Factory::__construct()。

请注意，使用CHECK_MODE_COERCE_TYPES或CHECK_MODE_APPLY_DEFAULTS将修改您的原始数据。

CHECK_MODE_EARLY_COERCE没有效果，除非与CHECK_MODE_COERCE_TYPES结合使用。如果启用，验证器将使用（并强制）它遇到的第一个兼容类型，即使模式定义了另一个直接匹配且不需要强制的类型。

运行测试

composer test                            # run all unit tests
composer testOnly TestClass              # run specific unit test class
composer testOnly TestClass::testMethod  # run specific unit test method
composer style-check                     # check code style for errors
composer style-fix                       # automatically fix code style errors

总结

使用JSON Schema能够让我们更轻易地对数据进行约束和验证，使在开发API时更加安心。在PHP中使用JSON Schema非常简单，只需要将数据和模式传入验证器中即可。希望本文能够帮助你更好地理解JSON Schema并应用于实际开发中。