很多刚接触编程、数据处理或大模型 API 的同学，都会遇到一个共同的问题：
JSON 看起来很自由，但也太自由了。
你永远不知道：
-
某个字段到底是不是必填
-
一个值到底应该是字符串还是数字
-
一个数组里应该放什么结构
-
数据格式什么时候算“合法”
这时候，JSON Schema 就派上用场了。
一、JSON 和 JSON Schema 各是干嘛的？
1️⃣ JSON 是“数据本身”
JSON 是一种数据表示格式，比如：
{
"name": "张三",
"age": 18,
"skills": ["Python", "SQL"]
}
它只负责 “长什么样”，不负责：
-
合不合法
-
字段全不全
-
类型对不对
2️⃣ JSON Schema 是“规则说明书”
JSON Schema 本质上是：
用 JSON 写的一份“JSON 规则文档”
它用来描述：
-
哪些字段必须有
-
每个字段的类型
-
数值范围、字符串长度
-
数组里元素的结构
一句话总结：
JSON = 数据 JSON Schema = 数据的法律
二、一个直观例子：为什么需要 JSON Schema？
假设你希望接收这样的用户信息：
{
"name": "李四",
"age": 25,
"email": "lisi@example.com"
}
你希望：
-
name：必须是字符串，必填 -
age：必须是整数，且 ≥ 0 -
email：必须是合法邮箱
如果没有 JSON Schema，你只能：
-
写一堆 if 判断
-
到处 try / except
-
靠文档和约定“祈祷别人别乱传”
JSON Schema 的目标就是：把这些规则写成一份统一、可校验的规范。
三、最简单的 JSON Schema 长什么样？
下面是一个完整但非常基础的 JSON Schema：
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
},
"required": ["name", "age"]
}
我们一条条解释。
1️⃣ type：整体数据类型
"type": "object"
说明：
整个 JSON 必须是一个对象（即
{}）
2️⃣ properties：字段定义
"properties": {
"name": { "type": "string" },
"age": { "type": "integer" }
}
含义：
-
允许有哪些字段
-
每个字段的类型是什么
常见类型包括：
-
string -
number -
integer -
boolean -
object -
array -
null
3️⃣ required：必填字段
"required": ["name", "age"]
含义：
- 如果缺少其中任何一个字段 → 不合法
四、用 Python 3 校验 JSON 是否符合 Schema
理论讲完了，我们来真正用起来。
1️⃣ 安装依赖
JSON Schema 在 Python 中的主流库是 jsonschema：
pip install jsonschema
2️⃣ 一个完整的 Python 示例
from jsonschema import validate, ValidationError
schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer", "minimum": 0}
},
"required": ["name", "age"]
}
data = {
"name": "王五",
"age": 20
}
try:
validate(instance=data, schema=schema)
print("数据合法 ✅")
except ValidationError as e:
print("数据不合法 ❌")
print(e)
运行结果：
数据合法 ✅
3️⃣ 如果数据不合法会怎样？
bad_data = {
"name": "赵六",
"age": -5
}
validate(instance=bad_data, schema=schema)
报错信息会明确告诉你：
-
哪个字段
-
为什么不符合规则
五、常见 Schema 能力速查表（非常实用）
1️⃣ 数值限制
{
"type": "integer",
"minimum": 0,
"maximum": 120
}
2️⃣ 字符串限制
{
"type": "string",
"minLength": 1,
"maxLength": 50
}
3️⃣ 正则校验（如邮箱）
{
"type": "string",
"pattern": "^[^@]+@[^@]+\\.[^@]+$"
}
4️⃣ 枚举值（只能选固定几种）
{
"type": "string",
"enum": ["male", "female", "unknown"]
}
5️⃣ 数组结构
{
"type": "array",
"items": {
"type": "string"
}
}
表示：
一个字符串数组
6️⃣ 嵌套对象（非常常见）
{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
}
}
}
六、JSON Schema 在真实项目中的典型用途
对小白来说，理解“我什么时候会用到它”非常重要。
✅ 1. 后端接口参数校验
-
前端 → 后端
-
客户端 → 服务端
-
第三方调用接口
JSON Schema = 自动化参数检查器
✅ 2. 配置文件校验
比如：
{
"db_host": "localhost",
"db_port": 3306
}
用 Schema 保证：
-
字段全
-
类型对
-
配置不乱写
✅ 3. 大模型 / Agent / Function Calling
你现在如果在玩：
-
OpenAI function calling
-
Tool calling
-
Agent 输入输出规范
你会发现：
JSON Schema 几乎是“官方语言”
✅ 4. 自动生成文档 & UI
很多工具可以：
-
根据 JSON Schema 自动生成表单
-
自动生成接口文档
-
自动校验输入
七、给初学者的几点实用建议
1️⃣ 别一开始就写很复杂的 Schema
先解决：
-
必填字段
-
基本类型
2️⃣ Schema 也是可以“演进”的
就像代码版本一样，慢慢加约束
3️⃣ 错误信息是朋友，不是敌人
JSON Schema 的报错非常详细，适合调试
八、总结一句话
JSON 负责表达数据
JSON Schema 负责约束数据
Python 负责执行规则
如果你：
-
在写接口
-
在做数据清洗
-
在用大模型
-
在做配置管理
那 JSON Schema 非常值得你认真学一次。
