什么是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()
。
Flag | Description |
---|---|
Constraint::CHECK_MODE_NORMAL
| 在「正常」模式下运行-这是默认设置 |
Constraint::CHECK_MODE_TYPE_CAST
| 为关联数组和对象启用模糊类型检查 |
Constraint::CHECK_MODE_COERCE_TYPES
| 尽可能转换数据类型以匹配架构 |
Constraint::CHECK_MODE_EARLY_COERCE
| 尽快应用类型强制 |
Constraint::CHECK_MODE_APPLY_DEFAULTS
| 如果未设置,则应用架构中的默认值 |
Constraint::CHECK_MODE_ONLY_REQUIRED_DEFAULTS
| 应用默认值时,仅设置必需的值 |
Constraint::CHECK_MODE_EXCEPTIONS
| 如果验证失败,立即引发异常 |
Constraint::CHECK_MODE_DISABLE_FORMAT
| 不验证「格式」约束 |
Constraint::CHECK_MODE_VALIDATE_SCHEMA
| 对架构以及提供的文档进行重新配置 |
请注意,使用
CHECK_MODE_COERCE_TYPES
或
CHECK_MODE_APPLY_DEFAULTS
将修改您的原始数据。
CHECK_MODE_EARLY_COERCE
没有效果,除非与
CHECK_MODE_COERCE_TYPES
结合使用。如果启用,验证器将使用(并强制)它遇到的第一个兼容类型,即使模式定义了另一个直接匹配且不需要强制的类型。
运行测试
composer test# run all unit tests
composer testOnly Test class # run specific unit test class
composer testOnly Test class::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并应用于实际开发中。