3 分钟了解 JSON Schema

程序员鱼皮

腾讯应用开发工程师

大家好，我不是鱼皮。

幸运又不幸，我是一名程序员，他也是一名程序员。

周末，我在开发网站，他在开发游戏，两个人一起写代码，一起写 Bug 头秃，竟也有了一丝别样的浪漫，好不自在！

今天，他遇到了一个后台的 Bug，游戏死活启动不了，我来帮忙排查一下，顺便给大家分享点编程小知识~

Bug 起因

在开始游戏时，首先要加载一些配置，比如玩家的用户名、关卡的难度、玩家的初始道具等。

由于游戏是使用 Java 语言开发的，他把这些配置封装成了一个对象，代码如下：

// 游戏配置
class GameConfig {
  // 玩家名
  String name;
  // 游戏难度
  int difficulty;
  // 玩家物品
  String[] items;

为了开发调试方便，他写了一个默认的配置；并且为了方便管理默认配置，把它单独存放到了一个 JSON 格式的文件中，而不是写死在代码里。

默认 JSON 配置文件如下：

{
  "name": "yupi",
  "difficulty": 5,
  "items": ["一级头", "二级甲"]

然后在程序中，读取该配置文件中的 JSON 字符串，再通过 Gson 解析库将 JSON 字符串转换为 Java 对象，就能获取到游戏配置信息，从而进行下一步处理了。

逻辑代码如下：

// 加载游戏配置
void loadConfig() {
  String jsonStr = loadFile('config.json');
  GameConfig config = new Gson()
    .fromJson(jsonStr, GameConfig.class);
  // 获取玩家名称
  String name = config.getName();
 // 更多处理

整个流程看起来非常简单，为啥会报错呢？

打印出异常信息，很明显，是 JSON 解析错误了：

仔细一看，哎，这小糊涂，配置文件竟然输错了，行尾少了个必要的引号，当然会解析失败了！

{
  // 行尾都少了个引号
  "items": ["一级头", "二级甲]

他表示很无奈，没办法，开发的时候配置越堆越多、改来改去，一不注意就少打个字符了。

我笑到：JSON 格式确实是很灵活强大的，我们在工作中，也经常会编写一些复杂的嵌套 JSON。我倒是知道一个办法，可以帮助减少 JSON 文件写错的概率。

他不以为然：哦，什么办法？用编辑器或者校验网站检查一下？

我：那也只能检查基本的语法吧，来来来，给你个更好康的神器 —— JSON Schema！

JSON Schema

JSON 格式的优点之一就是轻量，其本身并不支持写注释，所以没办法直接在文件本身中对字段进行描述。

因此，假如我们用 JSON 来做配置文件，大多数情况下都要对着文档来查看每个字段的类型、限制范围，才能编写出正确的配置。这样做不仅效率低，而且必须要自己来校验编写出的配置是否正确，一不小心就写错了。

而 JSON Schema 就是为解决此问题而生的，他本身就是 JSON 文件，用来注解和校验 JSON 文件。

举个例子，上面的游戏配置中，因为不小心输错了字符串数组导致程序出了 Bug。那可以编写一个 JSON Schema 来校验 items 字段是否为合法数组，代码如下：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.code-nav.cn/latest.json",
  "title": "GameConfig",
  "description": "游戏配置",
  "type": "object",
  "properties": {
    "items": {
      "type": "array"

在这个文件中，指定了 GameConfig 的类型必须为 object（对象），且 items 属性类型必须为 array（数组）。

接下来在要校验的数据中指定 "$schema" 字段为该校验文件地址，比如下列 JSON 配置，故意把 items 字段的值设置为 string（字符串）而非数组：

{
  "$schema": "https://www.code-nav.cn/latest.json",
   "name": "yupi",
   "difficulty": 5,
   "items": "haha"