JSON Schema 基础

什么是 JSON Schema？

JSON Schema 是一种用 JSON 来描述 JSON 结构的规范。

简单说：它是一份「数据说明书」，告诉你一段 JSON 数据「应该长什么样」。

JSON Schema（说明书）     JSON 数据（实际数据）
┌─────────────────┐     ┌─────────────────┐
│ type: "object"  │     │ {               │
│ properties: {   │ ───→│   "name": "张三",│  ← 符合说明书
│   name: ...     │     │   "age": 25     │
│ }               │     │ }               │
└─────────────────┘     └─────────────────┘

为什么需要 JSON Schema？

想象你要接收快递，但不提前说清楚尺寸：

❌ 不好的情况：
  快递员：给你寄了个「东西」
  你：……是多大的？（可能收到一个箱子，也可能收到一个包裹）

✅ 用 JSON Schema 的情况：
  快递员：寄一个 30×20×10cm 的纸箱
  你：收到 ✓ 尺寸匹配

在 API 中的作用：

• 定义请求体应该长什么样（前端/客户端按这个格式传）
• 验证响应体是否符合预期
• 在 AI 工具定义中，描述工具参数的结构

核心语法

1. 类型声明

{
  "type": "string"
}

常见类型：

2. 对象的结构描述

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "用户姓名"
    },
    "age": {
      "type": "integer",
      "description": "用户年龄"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name", "age"]
}

拆解：

• type: "object"：这是一个对象
• properties：定义了对象的每个字段及其类型
• required：哪些字段必须存在

3. 数组的描述

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "maxItems": 10
}

含义：这是一个字符串数组，最少 1 个元素，最多 10 个。

4. 枚举值（固定选项）

{
  "type": "string",
  "enum": ["celsius", "fahrenheit"]
}

含义：只能是 "celsius" 或 "fahrenheit"，不能是其他值。

5. 嵌套结构

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "contact": {
          "type": "object",
          "properties": {
            "email": { "type": "string" }
          }
        }
      }
    }
  }
}

类比：这就像一份入职登记表：

• 最外层 {} = 整个登记表
• user = 个人信息（又是一个子表格）
• contact = 联系方式（又是一个子表格）

在 AI API 中的实际应用

OpenAI 的工具定义

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "获取指定城市的天气",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "城市名"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["location"]
    }
  }
}

这里 parameters 就是一个完整的 JSON Schema，描述了 get_weather 工具需要什么参数。

Anthropic 的工具定义

{
  "name": "get_weather",
  "description": "获取指定城市的天气",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "城市名"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"]
      }
    },
    "required": ["location"]
  }
}

结构是一样的，只是字段名不同（parameters vs input_schema）。

常见约束关键字

OpenAI 的 strict 模式

OpenAI 的 function 定义支持 strict: true：

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "strict": true,  // ← 强制严格遵守 Schema
    "parameters": { ... }
  }
}

开启 strict: true 后：

• 模型必须严格按照 Schema 返回参数
• 不能多传字段，不能少传必填字段
• 类型必须完全匹配
• 不会输出 Schema 中未定义的参数

对比：Anthropic 没有这个开关，默认行为类似于「尽量遵守」，但不保证严格。

验证工具

在实际开发中，你会用 JSON Schema 验证数据：

在线工具：

• jsonschema.net — 可视化生成 Schema
• json-schema.org/implementations.html — 各语言验证库

代码中使用：

# Python
import jsonschema

schema = {"type": "object", "properties": {"name": {"type": "string"}}}
data = {"name": "张三"}

jsonschema.validate(data, schema)  # 通过

// JavaScript
import { validate } from 'jsonschema';

const schema = { type: 'object', properties: { name: { type: 'string' } } };
const data = { name: '张三' };

const result = validate(data, schema);  // result.valid === true

常见误区

实战建议

1. 先写 Schema，再写代码：把工具定义当作「合同」，前后端都按合同开发
2. 善用 description：给每个字段写清楚说明，AI 能更好地理解参数含义
3. 必填字段一定要标 required：避免 AI 漏传关键参数
4. 用 enum 限制选项：减少 AI 的猜测空间，提高准确性
5. 测试 Schema：用在线工具或代码验证，确保约束正确

返回 JSON 数据结构基础 了解 JSON 的基本类型和结构 返回 REST API 基础概念 了解 API 请求/响应的整体流程