JSON Schema 与结构化输出
从示例生成草稿 Schema、用 AJV 校验实例，并复制 OpenAI / Anthropic 片段。
仅为草稿，上线前务必人工审核。
JSON Schema 生成、校验与 LLM 结构化输出指南
JSON Schema 是 API 契约、OpenAPI 文档、网关校验和大模型结构化输出的共同基础。用真实示例生成草稿，再补充业务约束，通常比从空白文件手写更可靠。
FormaX 会根据示例值推断 type、required、object 和 array 结构，并用 AJV 校验实例。你仍然需要补充 enum、format、minimum、pattern 等业务规则。
常见使用场景
- API 契约设计：从真实响应示例快速生成 Schema 草稿，加速 OpenAPI 文档编写。
- 网关校验：在 API Gateway 或 BFF 层用 Schema 拦截不合规请求。
- LLM 结构化输出：为 GPT、Claude 等模型生成 function calling 或 response_format 配置。
- 前后端联调：统一请求/响应格式定义，减少字段遗漏和类型不一致。
- 数据质量检查：批量校验日志或导入数据是否符合预期结构。
从示例到可用 Schema
- 复制一份真实成功响应，删除不应公开的敏感字段。
- 生成草稿 Schema 后检查 required 字段是否符合业务预期。
- 为 ID、邮箱、日期、金额等字段补充 format、pattern 或范围限制。
- 使用校验面板测试缺字段、类型错误和边界值，再同步到 OpenAPI 或 LLM 配置。
适合作为示例的 JSON
{"id":1001,"email":"user@example.com","plan":"pro","active":true}推断不会替你决定业务规则
- 单个示例只能说明当前值的类型，不能证明字段全部可能取值。
- 数组为空时无法推断 item 类型，最好提供至少一个代表性元素。
- LLM 结构化输出场景下，应尽量添加 description，减少模型误填字段。
FAQ
生成的 Schema 可以直接上线吗？
建议作为草稿使用。上线前需要人工补充枚举、格式、范围和向后兼容要求。
为什么要用 AJV 再校验？
AJV 能模拟真实运行时的通过/失败结果，提前发现文档和实际 payload 不一致的问题。
JSON Schema 和 OpenAPI 有什么关系？
OpenAPI 3.x 的请求体和响应体定义基于 JSON Schema 的子集。生成的 Schema 可以直接嵌入 OpenAPI 文档。
如何为 LLM 生成 structured output 配置？
生成 Schema 后，工具会提供 OpenAI response_format 和 Anthropic tool 的代码片段，可直接复制到 API 调用中。
空数组为什么推断不出 item 类型？
空数组没有元素可供分析。提供一个包含代表性元素的示例，工具才能推断 items 的 type 和结构。
支持 JSON Schema Draft 哪个版本？
工具生成 Draft-07 兼容的 Schema，与 AJV 和大多数 OpenAPI 工具链兼容。
optional 字段会被标记为 required 吗？
推断时示例中出现的字段默认标记为 required。如果某些字段是可选的，需要手动从 required 数组中移除。
能校验嵌套很深的 JSON 吗？
可以。AJV 支持任意深度的嵌套 object 和 array 校验，性能对常规 API 响应足够。