BroadRouter
开始使用

JSON Schema

更新于

JSON Schema 是一套用 JSON 编写的词汇,用于描述和校验 JSON 数据的结构:类型、必填字段、允许的取值和嵌套。当前版本是 2020-12。大模型 API 用它来定义工具参数,以及结构化输出必须遵循的确切结构。

又称: JSON 模式定义、JSON 结构定义、JSON Schema 校验、json_schema、JSON Schema draft 2020-12

提示词里写一句“用 JSON 回复”,结构就只能靠运气。JSON Schema 把结构写下来,让机器可以检查。

工作原理

规范主要分两部分:Core “defines the basic foundation of JSON Schema”(译文:定义 JSON Schema 的基本基础),Validation “defines the validation keywords”(译文:定义校验关键字)。当前版本是 2020-12,上一版是 2019-09。

{
  "type": "object",
  "properties": {
    "name":    {"type": "string"},
    "amount":  {"type": "number", "minimum": 0},
    "currency": {"type": "string", "enum": ["SAR", "AED", "USD"]},
    "note":    {"type": ["string", "null"]}
  },
  "required": ["name", "amount", "currency", "note"],
  "additionalProperties": false
}

大模型 API 在两个地方用到 schema。工具定义把一个 schema 放在 parameters 里,用来描述参数。结构化输出则在 response_format 中以 {"type": "json_schema", "json_schema": {...}} 的形式发送一个 schema,OpenAI 说这 “ensures the model will match your supplied JSON schema”(译文:确保模型符合你提供的 JSON schema)。

OpenAI 的严格模式只接受一个子集。根据其“支持的 schema”一节:

  • 类型:string、number、boolean、integer、object、array、enum 和 anyOf。
  • 根节点必须是对象,且不能使用 anyOf。
  • 必须 additionalProperties: false,且每个字段都列在 required 中;要让字段变成可选,就允许它为 null,如上例中的 note。
  • 最多 5000 个对象属性、10 层嵌套,enum 取值总数最多 1000 个。
  • 不支持:allOf、not、dependentRequired、dependentSchemas、if、then、else。

为什么重要

  • 校验。 指导模型的那份 schema,也能在你的代码里检查它的回复。校验失败会给出确切的错误,可以直接发回给模型。
  • 可移植性。 按严格子集编写的 schema,比用尽所有关键字的 schema 能在更多服务商上使用。
  • Token。 工具定义里的 schema 每次请求都会作为输入发送。冗长的描述每一轮都要消耗 token。

在 BroadNet Inference 上

BroadNet 的 API 参考文档为 GLM 5.3 和 Qwen3.8 27B 说明了工具调用和结构化输出,但没有说明会强制执行哪些 schema 关键字。请把 schema 限制在上面那个简单子集内,并校验每一条回复。可以用 JSON Schema 生成器编写 schema,用 LLM JSON 输出校验器检查回复,完整示例见结构化输出一文。在其他模型上,请在提示词中要求 JSON 并校验回复;BroadNet 没有说明 JSON 模式,依赖它之前请先测试。

常见错误

  • 使用 allOf 或条件关键字,并以为服务器会强制执行。
  • 在严格模式下把字段从 required 里去掉来让它变成可选,而不是允许 null。

常见问题

大模型 API 支持完整的 JSON Schema 吗?

不支持。OpenAI 只支持一个子集:例如根节点必须是对象,每个字段都必须是必填,additionalProperties 必须为 false,并且不支持 allOf、not、if/then/else 等关键字。

JSON Schema 和 JSON 模式有什么区别?

JSON 模式只承诺输出合法 JSON。JSON Schema 则告诉模型和你的校验器,这个 JSON 必须包含哪些字段、各是什么类型。

BroadNet Inference 能用 JSON Schema 吗?

工具参数和结构化输出都使用 schema,这两者在文档中只对 GLM 5.3 和 Qwen3.8 27B 有说明。BroadNet 没有说明会强制执行哪些 schema 关键字,所以每条回复都要校验。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity