JSON Schema

j202312101422

239人浏览 · 2026-05-06 21:11:28

j202312101422 · 2026-05-06 21:11:28 发布

一、什么是 JSON Schema？

JSON Schema 是一种用来描述和验证 JSON 数据格式的规范。你可以把它理解成 JSON 的「说明书 + 校验规则」：

说明书：规定了 JSON 里应该有哪些字段、每个字段是什么类型（字符串 / 数字 / 数组 / 对象 / 空值等）。
校验规则：用来判断一份实际的 JSON 数据，是否符合你定义的格式要求，防止接口返回数据乱套。

在自动化测试里，它特别常用，用来验证接口返回的 JSON 数据结构是否正确。

二、结合代码逐行解释

下面这段代码，定义了一个 JSON Schema，我们一行一行看：

json_schema={
    "type": "object",
    "properties": {
        "addr":{
            "type": "null"
        },
        "data": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "age": {
                        "type": "number"
                    }
                }
            }
        }
    }
}

1. 根节点规则

"type": "object"

表示：被校验的 JSON 整体必须是一个对象（键值对形式），不能是数组、字符串等其他类型。

2. `properties`：定义对象里的字段规则

properties 用来描述这个对象里，每个字段的校验规则：

"properties": {
    "addr":{ ... },
    "data": { ... }
}

表示这个对象里，至少应该包含 addr 和 data 这两个字段。

3. 字段 `addr` 的规则

"addr":{
    "type": "null"
}

type: "null" 表示：addr 字段的值必须是 null（空值），不能是字符串、数字、对象等其他类型。
比如："addr": null 是合法的；"addr": "北京" 就是非法的。

4. 字段 `data` 的规则（重点）

"data": {
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "name": {
                "type": "string"
            },
            "age": {
                "type": "number"
            }
        }
    }
}

这部分是对数组类型的校验，我们拆开看：

"type": "array"表示：data 字段的值必须是一个数组，比如 []、[{}, {}] 这种形式。
"items": { ... }用来定义数组里每一个元素的校验规则。
数组元素的规则：
```
"type": "object",
"properties": {
    "name": { "type": "string" },
    "age": { "type": "number" }
}
```
表示：
- 数组里的每一个元素，都必须是一个对象；
- 这个对象里必须有 name 字段，且值为字符串；
- 这个对象里必须有 age 字段，且值为数字（整数或浮点数都可以）。

三、举个例子：合法 / 非法的 JSON

✅ 符合这个 Schema 的 JSON 示例

{
  "addr": null,
  "data": [
    {
      "name": "张三",
      "age": 20
    },
    {
      "name": "李四",
      "age": 25.5
    }
  ]
}

❌ 不符合的例子（随便改一个就会校验失败）

{
  "addr": "北京", // 这里不是 null，不合法
  "data": [
    {
      "name": "张三",
      "age": "20" // 这里 age 是字符串，不是数字，不合法
    }
  ]
}

四、Python 里怎么用它做校验？

一般用 jsonschema 库来校验，给你一个可直接运行的例子：

from jsonschema import validate

def test_04():
    # 定义你的 schema
    json_schema = {
        "type": "object",
        "properties": {
            "addr": {"type": "null"},
            "data": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "age": {"type": "number"}
                    }
                }
            }
        }
    }

    # 模拟接口返回的 JSON 数据
    mock_response = {
        "addr": null,
        "data": [
            {"name": "张三", "age": 20},
            {"name": "李四", "age": 25}
        ]
    }

    # 校验数据是否符合 schema
    validate(instance=mock_response, schema=json_schema)
    print("校验通过！")

如果校验失败，会直接抛出 ValidationError，告诉你哪里不符合规则，非常适合自动化测试。

💡 补充说明：