README

Hack JSON Schema 是一个用于在 Hack 中使用 JSON 模式验证 JSON 输入的库。

给定一个 JSON 模式文件，您可以使用 Hack 生成一个验证器来验证传入的 JSON 是否与该模式相符。如果 JSON 符合模式，验证器将返回类型化输出。

生成有以下好处

• 我们不必在运行时解析 JSON 模式来验证传入的对象。
• 我们可以输出从 JSON 模式生成的类型化形状，从而提高下游代码的类型安全性。

用法

Codegen::forPath

使用此库最基本的方法是从 JSON 模式文件生成一个验证器

use type Slack\Hack\JsonSchema\Codegen\Codegen;

Codegen::forPath('/path/to/json-schema.json', shape(
  'validator' => shape(
    'file' => '/path/to/MyJsonSchemaValidator.php',
    'class' => 'MyJsonSchemaValidator',
  ),
))->build();

/path/to/MyJsonSchemaValidator.php 现在存在一个类

final class MyJsonSchemaValidator extends BaseValidator {
  ... class contents
}

每个验证器都有一个 validate 方法，它接受一个解码后的 JSON 对象

$json = json_decode($args['json_input'], true);
$validator = new MyJsonSchemaValidator($json);
$validator->validate();
if (!$validator->isValid()) {
  print_r("invalid_json", $validator->getErrors());
  return;
}

// JSON is valid, get typed object:
$validated = $validator->getValidatedInput();

Codegen::forPaths

如果您有多个利用 $ref 属性的 JSON 模式，您应该优先使用 Codegen::forPaths 而不是 Codegen::forPath。

Codegen::forPath 的工作流程是

• 给定一个 JSON 模式，"取消引用"该模式。取消引用是解析所有 $ref 路径及其实际模式的过程。这创建了一个单一取消引用的方案。
• 使用取消引用的方案，生成一个验证器。

如果您只有一个主要方案，这效果很好，但如果您有多个方案，每个方案都有共同的引用，您将开始生成大量的重复代码。

在这些情况下，您可以使用 Codegen::forPaths。

use type Slack\Hack\JsonSchema\Codegen\Codegen;

$schemas = vec['/path/to/json-schema-1.json', '/path/to/json-schema-2.json', '/path/to/json-schema-3.json'];
Codegen::forPaths($schemas, shape(
  'validator' => shape(
    'refs' => shape(
       'unique' => shape(
          'source_root' => '/path/to',
          'output_root' => '/path/gen'
        )
     )
  ),
))->build();

通过定义 source_root 和 output_root，我们可以为每个遇到的 $ref 生成唯一的验证器。然后，我们可以重用这些验证器来生成其他验证器。

开发

安装依赖项

我们通过 Docker 处理所有依赖项。这很简单

make install

运行测试

make test

相关库

此库受到了以下相关库中想法的启发

• https://github.com/hhvm/hack-router-codegen
• https://github.com/justinrainbow/json-schema

许可

Hack JSON Schema 是 MIT 许可的。