什么是 JSON Schema？一文介绍

JSON Schema 是用于描述和验证 JSON 数据结构的标准规范。它定义了 JSON 数据应该具备的格式、类型、约束条件等规则，让开发者能够准确描述 API 接口的数据格式，并在数据传输过程中进行自动化验证。

JSON Schema 的基本概念

JSON Schema 本身就是一个 JSON 对象，它使用特定的关键字来描述数据的结构。通过这些关键字，可以定义数据的类型、取值范围、必填字段、数组长度等各种约束条件。

一个简单的 JSON Schema 示例：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name", "age"]
}

这个 Schema 定义了一个包含姓名、年龄和邮箱的用户对象，其中姓名和年龄是必填字段。

核心关键字说明

类型关键字：

type：定义数据类型，支持 string、number、integer、boolean、array、object、null
enum：限制值只能是指定的几个选项之一
const：限制值必须等于指定的常量

字符串约束：

minLength/maxLength：限制字符串最小/最大长度
pattern：使用正则表达式验证字符串格式
format：预定义格式验证，如 email、date、uri 等

数值约束：

minimum/maximum：数值的最小/最大值
multipleOf：数值必须是指定数的倍数

对象约束：

properties：定义对象属性
required：指定必填属性
additionalProperties：是否允许额外属性

数组约束：

items：定义数组元素的 Schema
minItems/maxItems：限制数组最小/最大长度
uniqueItems：数组元素是否必须唯一

嵌套和复杂结构

JSON Schema 支持嵌套结构，可以在对象属性中定义子对象或数组的 Schema：

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "profile": {
          "type": "object",
          "properties": {
            "avatar": {"type": "string"},
            "bio": {"type": "string"}
          }
        },
        "tags": {
          "type": "array",
          "items": {"type": "string"},
          "maxItems": 5
        }
      }
    }
  }
}

Schema 引用和重用

通过$ref关键字可以引用其他 Schema 定义，实现代码复用：

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": {"type": "string"},
        "city": {"type": "string"},
        "zipcode": {"type": "string"}
      }
    }
  },
  "type": "object",
  "properties": {
    "homeAddress": {"$ref": "#/$defs/address"},
    "workAddress": {"$ref": "#/$defs/address"}
  }
}

条件验证

JSON Schema 还支持条件逻辑，可以根据某些字段的值来应用不同的验证规则：

{
  "type": "object",
  "properties": {
    "accountType": {"enum": ["personal", "business"]},
    "taxId": {"type": "string"}
  },
  "if": {
    "properties": {"accountType": {"const": "business"}}
  },
  "then": {
    "required": ["taxId"]
  }
}

实际应用场景

JSON Schema 在 API 开发中发挥重要作用。后端开发者使用它定义接口的请求和响应格式，前端开发者根据 Schema 了解数据结构。在 API 测试阶段，Schema 可以自动验证接口返回的数据是否符合预期格式。

配置文件验证是另一个常见用途。应用程序的配置文件通常采用 JSON 格式，使用 Schema 可以在程序启动时验证配置的正确性，及时发现格式错误。

数据处理管道中，Schema 确保了数据在各个环节之间传递时保持一致的格式。当数据源发生变化时，Schema 验证能够快速识别格式不匹配的问题。

工具推荐

Apifox 是一款集成了 API 文档、API 调试、API 设计、API 测试、API Mock、自动化测试的 API 一体化协作工具，支持调试 HTTP、HTTP2、WebSocket、Socket、WebService、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件，它对 JSON Schema 提供了完整支持。

在 Apifox 中，你可以直接使用可视化编辑器创建和编辑 Schema，工具会自动生成对应的 JSON Schema 代码。Apifox 还提供 Schema 验证功能，在 API 测试过程中自动检查响应数据是否符合定义的 Schema 规范。

免费使用 Apifox