下面把 OpenAI 在 **Function Calling（Tools）** 与 Structured Outputs 中使用的 JSON Schema 规范讲清楚（基于 2024-08 正式版，strict: true 强约束）。

---

一、适用范围与两个场景

OpenAI 的 JSON Schema 主要用于两类场景：

1. Tools/Function Calling：描述工具参数（tools[].function.parameters）
2. 结构化输出（Structured Outputs）：描述整个回答的格式（response_format.json_schema）

两者底层是同一套 “JSON Schema 子集 + strict 约束”。

---

二、核心关键字（必掌握）

1）顶层结构（工具定义）

json

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "获取城市天气",
    "strict": true,
    "parameters": { /* JSON Schema 对象 */ }
  }
}

• strict: true：生产环境必须开启，强制模型 100% 符合 Schema。

2）parameters 里的标准字段（JSON Schema）

json

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "description": "城市名",
      "minLength": 2
    },
    "unit": {
      "type": "string",
      "enum": ["c", "f"]
    }
  },
  "required": ["city"],
  "additionalProperties": false
}

• type：只能是 object/string/number/integer/boolean/array/null。
• properties：对象的字段定义。
• required：必填字段数组（strict 下必须显式列出）。
• additionalProperties: false：strict 下每个 object 必须加，禁止模型输出额外字段。
• description：给模型看的说明，强烈建议每个字段都写。

---

三、支持的类型与写法（OpenAI 子集）

1）基础类型

• "type": "string"
• "type": "number"（浮点数）
• "type": "integer"（整数）
• "type": "boolean"
• "type": "null"（可与其他类型组合：["string", "null"]）

2）枚举

json

"unit": {
  "type": "string",
  "enum": ["c", "f", "k"]
}

• 枚举总数 ≤ 1000。

3）数组

json

"items": {
  "type": "object",
  "properties": { "name": {"type": "string"} },
  "required": ["name"],
  "additionalProperties": false
}

• items：数组元素的 schema。

4）嵌套对象

• 嵌套深度 ≤5 层。
• 每层都要写 additionalProperties: false。

5）联合类型（anyOf）

json

"value": {
  "anyOf": [
    { "type": "string" },
    { "type": "number" }
  ]
}

• 根不能是 anyOf。

6）不支持 / 限制

• 不支持 oneOf（部分文档提，但 strict 下不稳定）。
• 不支持 $ref 外部引用（内部 $defs 有限支持）。
• 不支持 patternProperties、dependencies 等复杂关键字。

---

四、strict: true 的强制规则（最重要）

一旦开启 strict: true：

1. 所有 object 必须写 additionalProperties: false。
2. 所有必填字段必须在 required 中显式列出。
3. 类型严格匹配：不能把 string 输出成 number。
4. 枚举值严格匹配：不能输出 enum 外的值。
5. 无额外字段、无缺失字段、无类型错误。→ 结果：模型输出一定是合法 JSON，且完全符合 SchemaOpenAI。

---

五、Tools 里的完整示例（可直接用）

json

{
  "type": "function",
  "function": {
    "name": "search_docs",
    "description": "搜索内部文档",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "搜索关键词",
          "minLength": 2
        },
        "top_k": {
          "type": "integer",
          "description": "返回条数",
          "minimum": 1,
          "maximum": 20
        },
        "filter": {
          "type": ["string", "null"],
          "description": "文档类型过滤"
        }
      },
      "required": ["query"],
      "additionalProperties": false
    }
  }
}

---

六、结构化输出（response_format）示例

json

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "meeting_summary",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "attendees": {
            "type": "array",
            "items": { "type": "string" }
          },
          "action_items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "task": { "type": "string" },
                "due_date": { "type": ["string", "null"] }
              },
              "required": ["task"],
              "additionalProperties": false
            }
          }
        },
        "required": ["title", "attendees", "action_items"],
        "additionalProperties": false
      }
    }
  }
}

---

七、最佳实践（生产环境）

1. 永远开启 strict: true。
2. 每个 object 都写 additionalProperties: false。
3. 必填字段全部列入 required。
4. 字段描述清晰，减少模型幻觉。
5. 类型尽量具体：能用 integer 不用 number，能用 enum 不用 string。
6. 嵌套不超过 5 层。