z-schema

z-schema npm 地址

z-schema github地址

JavaScript编写的 JSON Schema 验证器用于 NodeJS和浏览器。

version 3也在可以在浏览器中运行，你可以自己在这运行测试

Topics

• 用法（Usage）

• 特征（Features）

• 选项（Options）

• 基准点（Benchmarks）

用法（Usage）

验证器将尝试在可能的速度下执行同步验证，但在必要时支持异步回调。

CLI:

npm install --global z-schema
z-schema --help
z-schema mySchema.json
z-schema mySchema.json myJson.json
z-schema --strictMode mySchema.json myJson.json

NodeJS:

var ZSchema = require("z-schema");
var options = ... // see below for possible option values
var validator = new ZSchema(options);

同步模式：

var valid = validator.validate(json, schema);
// this will return a native error object with name and message
var error = validator.getLastError();
// this will return an array of validation errors encountered
var errors = validator.getLastErrors();
...

异步模式：

validator.validate(json, schema, function (err, valid) {
    ...
});

Browser:

<script type="text/javascript" src="../dist/ZSchema-browser-min.js"></script>
<script type="text/javascript">
    var validator = new ZSchema();
    var valid = validator.validate("string", { "type": "string" });
    console.log(valid);
</script>

远程引用和schemas：

如果您的架构中有一些远程引用，则必须在使用验证器之前下载这些schemas。否则，当试图编译schemas时，将获得UNRESOLVABLE_REFERENCE错误。

var validator = new ZSchema();
var json = {};
var schema = { "$ref": "http://json-schema.org/draft-04/schema#" };

var valid = validator.validate(json, schema);
var errors = validator.getLastErrors();
// valid === false
// errors.length === 1
// errors[0].code === "UNRESOLVABLE_REFERENCE"

var requiredUrl = "http://json-schema.org/draft-04/schema";
request(requiredUrl, function (error, response, body) {

    validator.setRemoteReference(requiredUrl, JSON.parse(body));

    var valid = validator.validate(json, schema);
    var errors = validator.getLastErrors();
    // valid === true
    // errors === undefined

}

如果能够同步加载schemas，则可以使用ZSchema.setSchemaReader特性：

ZSchema.setSchemaReader(function (uri) {
    var someFilename = path.resolve(__dirname, "..", "schemas", uri + ".json");
    return JSON.parse(fs.readFileSync(someFilename, "utf8"));
});

特征

• Validate against subschema

• Compile arrays of schemas and use references between them

• Register a custom format

• Automatic downloading of remote schemas

• Prefill default values to object using format

• Define a custom timeout for all async operations

• Disallow validation of empty arrays as arrays

• Disallow validation of empty strings as strings

• Disallow schemas that don't have a type specified

• Disallow schemas that contain unrecognized keywords and are not validated by parent schemas

• Assume additionalItems/additionalProperties are defined in schemas as false

• Force additionalItems/additionalProperties to be defined in schemas

• Force items to be defined in array type schemas

• Force minItems to be defined in array type schemas

• Force maxItems to be defined in array type schemas

• Force minLength to be defined in string type schemas

• Force maxLength to be defined in string type schemas

• Force properties or patternProperties to be defined in object type schemas

• Ignore remote references to schemas that are not cached or resolvable

• Ignore case mismatch when validating enum values

• Only allow strictly absolute URIs to be used in schemas

• Turn on z-schema strict mode

• Set validator to collect as many errors as possible

• Report paths in errors as arrays so they can be processed easier

验证 subschema

如果由于任何原因不想使用引用，将schema分割为多个schema，则可以在验证时使用schemaPath选项：

var valid = validator.validate(cars, schema, { schemaPath: "definitions.car.definitions.cars" });

在 test 中查看更多细节。

编译schemas数组并使用它们之间的引用

可以使用验证器编译具有它们之间的引用的schema数组 ， 然后对其中一个schema进行验证。

var schemas = [
    {
        id: "personDetails",
        type: "object",
        properties: {
            firstName: { type: "string" },
            lastName: { type: "string" }
        },
        required: ["firstName", "lastName"]
    },
    {
        id: "addressDetails",
        type: "object",
        properties: {
            street: { type: "string" },
            city: { type: "string" }
        },
        required: ["street", "city"]
    },
    {
        id: "personWithAddress",
        allOf: [
            { $ref: "personDetails" },
            { $ref: "addressDetails" }
        ]
    }
];

var data = {
    firstName: "Martin",
    lastName: "Zagora",
    street: "George St",
    city: "Sydney"
};

var validator = new ZSchema();

// compile & validate schemas first, z-schema will automatically handle array
var allSchemasValid = validator.validateSchema(schemas);
// allSchemasValid === true

// now validate our data against the last schema
var valid = validator.validate(data, schemas[2]);
// valid === true

注册自定义格式

你可以注册任何你自己的格式。您的同步验证函数应该始终用boolean响应：

ZSchema.registerFormat("xstring", function (str) {
    return str === "xxx";
});

还支持异步格式验证器，它们应该接受两个参数、值和它们需要响应的回调：

ZSchema.registerFormat("xstring", function (str, callback) {
    setTimeout(function () {
        callback(str === "xxx");
    }, 1);
});

帮助检查已注册的格式的Help方法

var registeredFormats = ZSchema.getRegisteredFormats();
//registeredFormats will now contain an array of all formats that have been registered with z-schema

远程schemas的自动下载

远程模式的自动下载已经从3.x版本中移除，但是仍然可以使用一些额外的代码，有关这方面的更多信息，请参阅此测试。

使用格式预填充默认值到对象

使用格式，您可以预先将选择的值填充到这样的对象中：

ZSchema.registerFormat("fillHello", function (obj) {
    obj.hello = "world";
    return true;
});

var data = {};

var schema = {
    "type": "object",
    "format": "fillHello"
};

validator.validate(data, schema);
// data.hello === "world"

选项（Options）

asyncTimeout

定义一个时间限制，在ASYNC_TIMEOUT错误导致验证失败之前，在等待异步任务（如异步格式验证器）执行验证时，应该使用这个时间限制。

var validator = new ZSchema({
    asyncTimeout: 2000
});

noEmptyArrays

当为true时，验证器将假定任何数组中的项的最小计数为1，除非minItems: 0被显式定义。

var validator = new ZSchema({
    noEmptyArrays: true
});

noEmptyStrings

如果为true，则验证器假定任何字符串的传递字符串类型验证的最小长度为1，除非minLength: 0是显式定义的。

var validator = new ZSchema({
    noEmptyStrings: true
});

noTypeless

如果为true，则验证器将对没有指定期望的对象类型的schemas进行验证失败。

var validator = new ZSchema({
    noTypeless: true
});

noExtraKeywords

当为true时，验证器将无法验证使用JSON Schema规范中未定义的关键字、且未在$schema属性中提供父schema来验证schema。

var validator = new ZSchema({
    noExtraKeywords: true
});

assumeAdditional

当为true时，验证器假设additionalItems/additionalProperties被定义为false，因此您不必手动修复所有schemas。

var validator = new ZSchema({
    assumeAdditional: true
});

当为一个数组时，验证器假设additionalItems/additionalProperties被定义为false，但是允许一些属性通过。

var validator = new ZSchema({
    assumeAdditional: ["$ref"]
});

forceAdditional

当为true时，验证器不验证schemas，其中additionalItems/additionalProperties应该定义为true或false。

var validator = new ZSchema({
    forceAdditional: true
});

forceItems

如果为true，则验证程序不验证schemas中item没有为array类型的schemas。这是为了避免通过数组定义传递任何内容。

var validator = new ZSchema({
    forceItems: true
});

更多的参数参见链接

基准点（Benchmarks）

那么它如何与version 2.x和其他版本相比呢？

注意:这些测试纯粹是面向对象的，它们不考虑任何验证器的额外特性

rawgithub.com/zaggino/z-schema/master/benchmark/results.html