关于json:得物技术浅谈jsonschema入门教程

0次阅读

共计 9424 个字符，预计需要花费 24 分钟才能阅读完成。

文章简介：
大白话介绍 json-schema，基本概念到高阶用法，由浅入深，结合实际利用剖析 json-schema 的理论作用。

在答复这个问题之前，咱们先理解一下它产生的背景。

随着互联网的倒退，前后端交互，由最后的 text/html，image/* 图片等文件流，到目前的 application/x-www-form-urlencoded，multipart/form-data，application/json 流，以及将来的 application/octet-stream 二进制。但毫无疑问，目前最风行的前后端交互的格局是 application/json，也是咱们开发者开发过程中利用最多的格局。

除此之外，json 在前端的利用也越来越重要，无论将来如何倒退，它始终有着不可或缺的重要位置，为什么呢？笔者认为最基本的起因是它实质上是一个对象，面向对象编程作威作福的明天，自然而然，它的霸主位置便无奈被撼动，同时它的轻量化，高可读，强扩大，高传输效率，也是一种重要起因，它正在为人与机器之间的交互扮演着一个重要的媒介角色。

正是因为 json 利用越来越宽泛，与它相干的工具因而利用而生，json-schema 就是其中之一。

假如咱们有这样一种 JSON 数据格式：

{
    "id": "1432423230",
    "name": "Jeck",
    "sex": "male"
}

只管这段 json 对开发的人来说简单明了，咱们很容易就晓得它是示意一个 Person 的字符串，但依然存在一些问题，例如：

id 能够是数字吗？
name 有多少字符限度吗？
sex 是必须的吗？能够是 man 和 woman 吗？

兴许作为我的项目的创始人会非常分明这些字段代表的含意，然而随着我的项目的增大，过了一年当前，他未必能想起来这些字段的含意，作为代码的初始开发者尚且如此，那接管我的项目的其余保护人更不用说了。

只管上述 json 代码咱们都晓得什么含意（Person），外面的字段每个人的了解可能就会不一样，咱们只能简略地依据属性英文的意思了解它的含意，但咱们不能假设每个人的英语水平都很高，制订的属性值都能让其他人能一眼就看出什么含意。

所以，在团队日益凸显重要的明天，为团队独特指定一套 json 的标准就十分必要，让团队对它的了解是统一的，以此达到这样的目标：

缩小了解老本；
进步开发效率；
升高保护老本。
那么回过头来，再答复一下什么是 json-schema 呢？置信聪慧的你曾经猜到了。

对，没错，就是 json 的一套标准，也有人说它是校验 json 的一套利器，是一个提议的 IETF 规范……其实都是一个含意。

如果你相熟 typescript 或者 flow，那么很快就能帮你理出这样的一套关系：

json-schema 之于 json，就如同 typescript(或 flow) 之于 javascript

形成 JSON 的两种根本类型：Object 和 Array

其中 value 的值为：string,number,object,array,boolean, null

tips：没有 undefined 类型

既然是一套标准，那么就会有很多的语义，那么咱们从最简略的例子开始介绍，如下：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/person.schema.json",
  "title": "Person",
  "description": "it is a person object",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for a person",
      "type": "string"
    }
  },
  "required": ["id"]
}

通常状况下，咱们见得最多的格局和属性是 type 和 properties，用于形容一个对象，用于形容一个数组的是 items。

id 时形容人的惟一标记，相似咱们的身份证号码，这是对这条数据的惟一标识符，对数据库而言，它是必须的，同时咱们限定了它的类型为 string。

name 是形容人的符号，这更靠近人类的应用习惯，计算机通常重视标识符 ID，而人类通常更重视姓名，因而它通常也是必须的，且限定它的最大长度为 50。

description 示意该字段的形容，使人更明确这个属性值想要表白的意思。

type 限度该字段的类型。

required 是验证必填的属性列表，不填示意不验证，属性忽然的减少和缩小都不会验证。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/person.schema.json",
  "title": "Person",
  "description": "it is a person object",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for a person",
      "type": "string"
    },
    "name": {
      "description": "The identifier for a person",
      "type": "string",
      "maxLength": 50
    }
  },
  "required": ["id", "name"]
}

同时咱们须要对性别进行标准，不然对同一含意的男性，一个人的了解为 male，另一个了解为 man。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/person.schema.json",
  "title": "Person",
  "description": "it is a person object",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for a person",
      "type": "string"
    },
    "name": {
      "description": "The identifier for a person",
      "type": "string",
      "maxLength": 50
    },
    "sex": {
      "description": "The gender of the person",
      "type": "string",
      "enum": ["male", "female"]
    },
  },
  "required": ["id", "name"]
}

忽然有一天，需要变了，产品经理说须要退出另外一个属性 age 年龄，年龄不能低于 0 吧，更不能大于 1000～

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/person.schema.json",
  "title": "Person",
  "description": "it is a person object",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for a person",
      "type": "string"
    },
    "name": {
      "description": "The identifier for a person",
      "type": "string",
      "maxLength": 50
    },
    "sex": {
      "description": "The gender of the person",
      "type": "string",
      "enum": ["male", "female"]
    },
    "age": {
        "description": "The age for a person",
        "type": "number",
        "exclusiveMinimum": 0,
        "maximum": 1000
    }
  },
  "required": ["id", "name"]
}

其中 exclusiveMinimum 是大于的意思，如果想蕴含 0 作为无效年龄，咱们将指定 minimum 作为关键字，示意大于等于的意思，对应地，maximum 和 exclusiveMaximum 则别离取值为小于等于和小于。

晓得了一个人的姓名和年龄，仿佛还短少了什么，试想一下，你见到帅哥或美女后，很侥幸的是你们胜利搭讪上了，而且还聊得挺开心的，那么将要离别的最初一件很重要事是啥？

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/person.schema.json",
  "title": "Person",
  "description": "it is a person object",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for a person",
      "type": "string"
    },
    "name": {
      "description": "The identifier for a person",
      "type": "string",
      "maxLength": 50
    },
    "sex": {
      "description": "The gender of the person",
      "type": "string",
      "enum": ["male", "female"]
    },
    "age": {
        "description": "The age for a person",
        "type": "number",
        "exclusiveMinimum": 0,
        "maximum": 1000
    },
    "phone": {
        "description": "The contact for a person",
        "type": "string",
        "pattern": "^[13|14|15|16|17|18|19][0-9]{9}$"
    }
  },
  "required": ["id", "name"]
}

字符串束缚反对正则表达式的形容，应用 pattern 关键字。

随着 90 及 00 后的崛起，他们是一群有着幻想和谋求自我的人，因而他们会越来越重视本人的共性和标签，而咱们的起初我的项目竟然没有这一内容字段。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/person.schema.json",
  "title": "Person",
  "description": "it is a person object",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for a person",
      "type": "string"
    },
    "name": {
      "description": "The identifier for a person",
      "type": "string",
      "maxLength": 50
    },
    "sex": {
      "description": "The gender of the person",
      "type": "string",
      "enum": ["male", "female"]
    },
    "age": {
        "description": "The age for a person",
        "type": "number",
        "exclusiveMinimum": 0,
        "maximum": 1000
    },
    "phone": {
        "description": "The contact for a person",
        "type": "string",
        "pattern": "^[13|14|15|16|17|18|19][0-9]{9}$"
    },
    "tags": {
        "description": "The labels to describe a person",
        "type": "array",
        "items": [{ "type": "string"}
        ],
        "minItems": 1,
        "uniqueItems": true
    },
  },
  "required": ["id", "name"]
}

引入 items 规定数组的每一项，要求数组中的内容为 string 类型，同时如果申明了这个字段 tags，那么 minItems 规定它的标签至多有一个以上，且 uniqueItems 规定每个标签都是惟一的。

咱们通常遇到的数据都不是扁平的，层级个别都会比拟深，这里引入给它增加上一个地址字段。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://example.com/person.schema.json",
  "title": "Person",
  "description": "it is a person object",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique identifier for a person",
      "type": "string"
    },
    "name": {
      "description": "The identifier for a person",
      "type": "string",
      "maxLength": 50
    },
    "sex": {
      "description": "The gender of the person",
      "type": "string",
      "enum": ["male", "female"]
    },
    "age": {
        "description": "The age for a person",
        "type": "number",
        "exclusiveMinimum": 0,
        "maximum": 1000
    },
    "phone": {
        "description": "The contact for a person",
        "type": "string",
        "pattern": "^[13|14|15|16|17|18|19][0-9]{9}$"
    },
    "tags": {
        "description": "The labels to describe a person",
        "type": "array",
        "items": [{ "type": "string"}
        ],
        "minItems": 1,
        "uniqueItems": true
    },
    "address": {
        "description": "The address for a person",
        "type": "object",
        "properties": {
            "country": {"type": "string"},
            "province": {"type": "string"},
            "city": {"type": "string"},
            "region": {"type": "string"},
            "detail": {"type": "string"}
        },
        "required": ["country", province","city","region"]
    },
  },
  "required": ["id", "name"]
}

最初，让咱们来看一下咱们定义的 json 应该是怎么的。

{
    "id": "A000000000",
    "name": "溥仪",
    "sex": "male",
    "age": 112,
    "phone": "1300000000",
    "tags": ["吃饭","睡觉","发愣","末代皇帝"],
    "address": {
        "country": "天朝",
        "province": "帝都",
        "city": "帝都",
        "region": "东城区",
        "detail": "景山前街 4 号故宫博物馆",
    }
}

更多的属性标准请移步官网：https://json-schema.org/draft…

大到宇宙飞船，小到家常日用手机，这个世界上很多省事的货色正因为懒才发明进去的，可恶的攻城狮们也是这样一群有智慧的动物。很多程序咱们只想写一遍，比方上述的地址定义，有这样一种场景，一个人的地址能够有很多种，比方收件地址和发送地址，它们可能包含学校地址，公司地址，家庭地址，租房地址等等。而它们的构造都是雷同的，那么咱们就不可能反复定义那么多地址信息了，而 json-schema 也是反对这一操作的。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
      "address": {
        "type": "object",
        "properties": {
            "country": {"type": "string"},
            "province": {"type": "string"},
            "city": {"type": "string"},
            "region": {"type": "string"},
            "detail": {"type": "string"}
        },
        "required": ["country", province","city","region"]
    },
  },
  
  "type": "object",
  
  "properties": {
        "receipt_address": {"#ref": "#/definitions/address"},
        "send_address": {"#ref": "#/definitions/address"}
  }
}

亦或者联合 $id 和 $ref 进行援用解决。

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
      "address": {
        "$id": "#address",
        "type": "object",
        "properties": {
            "country": {"type": "string"},
            "province": {"type": "string"},
            "city": {"type": "string"},
            "region": {"type": "string"},
            "detail": {"type": "string"}
        },
        "required": ["country", province","city","region"]
    },
  },
  
  "type": "object",
  
  "properties": {
        "receipt_address": {"#ref": "#address"},
        "send_address": {"#ref": "#address"}
  }
}

通过下面咱们晓得用 $ref 能够解决共用的问题，那么进一步咱们能够是否能够了解为本人能够调用本人，进而造成递归？yes, we can!

最常见的就是 html 的 dom 构造，它自身就是用递归来生成 dom 的，举个栗子:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
      "element": {
        "$id": "#element",
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "props": {
                "type": "object",
                "properties": {},},
            "children": {
                "type": "array",
                "items": {"$ref": "#element"},
            },
        }
    },
  },
  
  "type": "object",
  
  "properties": {
        "element": {"#ref": "#element"}
  }
}

须要留神的是，递归调用的时候，不要呈现 a 和 b 的互相援用，否则会造成死循环。

思考到网络带宽和开发效率，通常理论的利用中咱们都会省略很多，下面的形容有些会显得冗余，让咱们来看一个理论的利用。以 @formily/antd 为例。

上述内联布局对应 json-schema 为：

{
  "type": "object",
  "properties": {
    "aaa": {
      "key": "aaa",
      "name": "aaa",
      "type": "string",
      "title": "字段 1",
      "x-component": "input"
    },
    "bbb": {
      "key": "bbb",
      "name": "bbb",
      "type": "number",
      "title": "字段 2",
      "x-component": "numberpicker"
    },
    "ccc": {
      "key": "ccc",
      "name": "ccc",
      "type": "date",
      "title": "字段 3",
      "x-component": "datepicker"
    }
  }
}

上述 type 规定了属性值的输出值类型应该是什么，比照你会发现用于验证的 json-schema 数据就只有。

{
  "type": "object",
  "properties": {
    "aaa": {"type": "string",},
    "bbb": {"type": "number",},
    "ccc": {"type": "date",}
  }
}

tips: 上述的 ”type”:”date” 是 draft7 新增的类型。

在 @formily/antd 理论利用中，校验属性与业务属性是混合在一起的，严格意义上说它并不是一个规范的 json-schema，它联合本人的理论业务制订了一套属于本人的 json-schema，你能够了解为伪 json-schema，但它值得咱们借鉴和学习。

通常状况下，咱们还能够通过应用第三方工具来被动验证咱们写的 json 的合法性，如 jsonschema，react 的 form 表单 schema 校验 react-jsonschema-form。

明天这里只是介绍了 json-schema 的一些根底用法，只是它的冰山一角，它还有很多弱小的性能，如 dependencies，additionalItems，consts, allOf, anyOf, oneOf, not, if……then……else 等等，更多的玩法能够去 json-schema 官网。

最初，让咱们总结一下 json-schema 的基础知识，它是一套用于校验 json 的标准，让读写都同时遵循的一套规定。

由小及大，咱们再将 json-schema 拆解一下，那么什么是 schema 呢？

维基百科给出的定义是:

The word schema comes from the Greek word σχῆμα (skhēma), which means shape, or more generally, plan.

严格意义上，schema 是一种架构或模式，在数据库系统中是形式语言形容的一种构造，是对象的汇合。

触类旁通，就会有 xml-schema，yaml-schema……它们指的都是 XXX 数据的一种标准和模式。

json-schema 官网：https://json-schema.org/
json-schema 应用教程文档：http://xaber.co/2015/10/20/JS…
@formily/antd 的 SchemaForm：https://formilyjs.org/#/0yTeT…

文|Alan

关注得物技术，携手走向技术的云端

正文完

json

发表至： json

2021-05-14

0

关于json:攻略-如何实现一个满足业务需求的流程设计器

关于json:JSON数据如何进行解析呢方式有哪些

关于json:实时数仓-Hologres推出计算组实例支持JSON数据向量计算大模型等新能力

关于json:Y-分钟速成-json

关于前端:插件式可扩展架构设计心得

关于json:得物技术浅谈jsonschema入门教程

一、缘起

什么是 json-schema？

二、介绍

1）根本类型

2）基本概念

3）定义属性值

4）深刻理解属性

5）嵌套构造

三、高阶用法

1）重用

2）递归

四、理论利用

五、总结

参考

站内搜索