你不知道的JSON Schema

未标题-1.png

1、JSON？

JSON(JavaScript Object Notation) 是一种轻量级的数据交换格式。具有简洁、可读性高、支持广泛的特点。

下面我们用JSON描述了一个商品的基本信息，包含了JSON的一些基本数据的类型。

1{
2  "productId": 1,                  
3  "productName": "HUAWEI Mate X2", 
4  "price": 17999,                   
5  "tags": [ "秒杀", "自营" ] 
6}

2、Json Schema？

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.

JSON Schema是一个帮助你定义、校验甚至是修复json数据格式的解决方案。它定义了一整套规则，允许我们通过定义一个schema(本身也是JSON)来描述一个JSON串的数据格式。

下面我们通过Json Schem对上面的商品信息进行描述。同时明确我们需要约束的json属性。

1{
2  "type": "object",
3  "title": "手机商品",
4  "description": "手机商品详情",
5  "properties": {
6    "productId": {
7      "description": "商品id",
8      "type": "integer"
9    },
10    "productName": {
11      "description": "商品名称",
12      "type": "string"
13    },
14    "price": {
15      "description": "商品价格",
16      "type": "number",
17      "exclusiveMinimum": 0
18    },
19    "tags": {
20      "description": "商品标签",
21      "type": "array",
22      "items": {
23        "type": "string"
24      },
25      "minItems": 1,
26      "uniqueItems": true
27    }
28  },
29  "required": ["productId", "productName", "price"]
30}

我们来简单分析一下上面的JSON Schema。

{}

1{
2  "type": "object",   // 约束对象是object，
3  "title": "手机商品",  //
4  "description": "手机商品详情",  //描述信息 非必须
5  "properties": {
6			... // 这里是object中具体属性的约束
7  },
8  "required": ["productId", "productName", "price"] // 当前数据对象必须包含productId，productName，price三个字段
9}

productId

1"productId": {
2      "description": "商品id",
3      "type": "integer"  // 约束productid属性类型为整型
4   }

productName

1 "productName": {
2      "description": "商品名称",
3      "type": "string"  //约束productName属性类型为字符型
4    },

price

1"price": {
2      "description": "商品价格", 
3      "type": "number",  // 约束price属性类型为数字型，可以是整型或浮点型。
4      "exclusiveMinimum": 0 // 约束该数字>0（不包含0）
5    },

tags

1 "tags": {
2      "description": "商品标签",
3      "type": "array", // 约束tag属性是数组
4      "items": {
5        "type": "string" // items是数组项约束，这里约束数组项均为字符型
6      },
7      "minItems": 1, // 约束该数组至少包含1项
8      "uniqueItems": true // 约束数组中每项不得重复
9    }

通过上面的例子，相信大家应该对Json Schema有了初步的了解。更多关于Json Schema关键词的的介绍大家可以参照 JSON Schema 规范。

3、Json Schema 应用

1、数据校验。

在实际的业务开发中我们经常有对大量数据进行校验的场景。比如中后台系统中的表单提交、自动化接口测试等等。

这里推荐Ajv.js ，适用于Node.js和浏览器的高性能JSON验证器。

简单示例 CodePen。

1import Ajv from "ajv"
2const ajv = new Ajv()
3// JSON Schema
4const schema = {
5	  ...
6}
7const validate = ajv.compile(schema)
8// 待验证数据
9const validData = {
10   ...
11}
12const validResult = validate(validData)
13if (validResult) {
14  console.log('验证通过')
15} else {
16  console.log(validate.errors) // 错误详细信息
17}

2、基于JSON Schema的表单自动生成方案。

上面对数据进行校验的例子是对是在数据输出端保证数据的正确性，有没有什么方式能在数据输入时就保证数据正确性呢？

我们通过对JSON Schema的观察可以发现，每一条Schema数据其实都可以对应一种表单UI的展示。表单的UI逻辑中保证在提交表单前，数据就是符合Schema规则的，表单验证通过后，得到的就是符合 Schema约束的 JSON 数据。

这里为大家推荐我在实际开发中调研过且在 github上start靠前的几个库。

1、react

react-jsonschema-form
FormRender 官方提供了可视化JSON Schema生成工具。点击链接

2、vue

vue-json-schema-form 官方提供了可视化JSON Schema生成工具。点击链接

另外这几个库都支持开发者去实现自定义模板，将我们在业务开发中封装的表单组件扩展到JSON Schema的约束规范中。

3：其他好玩的库

typescript-json-schema

通过在TypeScript文件中添加注释关键词。基于TS代码生成 JSON Schema。同时支持作为命令行工具使用和通过代码调用。

接下来我们把上面的商品信息改用ts描述一下

1export interface Product {
2  /**
3   * @minimum 0
4   * @TJS-type integer
5   */
6  productId: number;
7  productName: string;
8  /**
9    * @exclusiveMinimum 0
10    */
11  price: number;
12  /**
13   *  @minItems 1
14   *  @uniqueItems  true
15   */
16  tags: Array<string>
17}

运行

1> npx typescript-json-schema 'index.ts' 'Product' -o test.json

可以得到我们上面定义商品的JSON Schema文件。

文章最后感谢大家阅读，如果你有更好的对JSON Schema的应用，欢迎在评论区留言讨论。