xsAI生态中的Schema统一:xsschema转换与校验完全指南(Zod、Valibot、ArkType)
xsAI生态中的Schema统一:xsschema转换与校验完全指南(Zod、Valibot、ArkType)
在 AI 应用开发中,数据校验与结构化输出是新手最容易卡住的环节:Zod、Valibot、ArkType 各有一套 API,模型却只认 JSON Schema。xsAI 生态中的 xsschema 包基于 Standard Schema 标准解决了这个问题——它能把上述三种(甚至更多)库的 Schema 统一转换为 JSON Schema,并对数据做统一校验,一套心智模型通吃全生态。
为什么需要 Schema 统一
xsAI 的所有操作(generateText、streamText、工具调用等)都需要把"数据结构"告诉 AI 模型。但各家校验库的私有格式模型并不认识,必须翻译成通用的 JSON Schema。
💡 换句话说,xsAI 生态里 Schema 承担两个独立职责:
| 职责 | 说明 | 谁负责 |
|---|---|---|
| 转换 | 把 Zod / Valibot / ArkType 等库的 Schema 转成 JSON Schema 交给模型 | xsschema 的 toJsonSchema |
| 校验 | 用 Schema 验证真实数据 | 任何实现了 Standard Schema 的库都可以 |
如果你的库原生支持 Standard JSON Schema(例如 Zod 4),xsAI 的 tool() 和 outputFormat 会直接接收,无需转换;对没有原生支持的库,就需要 xsschema 出手。
三步上手:安装 xsschema 并运行第一个转换
xsschema 是独立小包,按需安装即可:
pnpm add xsschema zod
最小示例——定义一个 Zod 对象,然后分别"转换"和"校验":
import { toJsonSchema, validate } from 'xsschema'
import * as z from 'zod'
const schema = z.object({ name: z.string() })
console.log(await toJsonSchema(schema))
console.log(await validate(schema, { name: 'Ada' }))
就这么简单:toJsonSchema 负责"翻译给模型看",validate 负责"验证真实数据"。
两大核心 API 详解
toJsonSchema:任何 Standard Schema → JSON Schema
toJsonSchema(schema) 返回 Promise<JsonSchema>,内部走一条清晰的决策链(见 packages/xsschema/src/to-json-schema/index.ts):
- 先查原生支持:如果 Schema 暴露了
~standard.jsonSchema,直接以draft-07为目标取输入 Schema,不加载任何额外依赖; - 再按 vendor 加载转换器:否则根据
~standard.vendor动态import对应库的转换器(实现见 packages/xsschema/src/to-json-schema/vendors/index.ts); - 依赖缺失即报错:转换器包没装或库无法表达时,Promise 直接 reject。
⚠️ 注意它之所以是
async,正是因为需要动态加载 vendor 依赖——这也是树摇和按需加载的代价。
validate:统一的数据校验入口
validate(schema, input) 返回 Schema 输出类型的 Promise,规则很直白(见 packages/xsschema/src/validate.ts):
- ✅ 校验通过 → 返回(可能被 Schema 转换过的)值;
- ❌ 校验失败 → 抛出
Error,错误信息就是问题列表的 JSON 字符串,方便直接展示给模型或日志系统。
它不关心 Schema 来自哪一家库,只要实现了 Standard Schema 就能用——这就是"统一"二字的分量。
两个实用辅助函数
| 函数 | 行为 |
|---|---|
jsonSchema(schema) |
原样返回你传入的 JSON Schema,不做任何校验,适合手动编写 Schema 的场景 |
strictJsonSchema(schema) |
返回副本,并在对象上递归添加 additionalProperties: false |
strictJsonSchema(见 packages/xsschema/src/json-schema.ts)适合结构化输出场景:xsAI 的 outputFormat 始终以 strict 模式发送 Schema,防止模型"夹带"多余字段。注意它只递归处理直接嵌套的 object 属性,不深入数组元素、union 和引用,也不会把字段变成 required。
Zod、Valibot、ArkType 三大库实战对照
支持的库与依赖清单
| 库 | 需要安装的包 |
|---|---|
| 原生 Standard JSON Schema | 库本身即可 |
| Zod 4 / Zod Mini | zod |
| Zod 3 | zod + zod-to-json-schema |
| Valibot | valibot + @valibot/to-json-schema |
| ArkType | arktype |
| Effect Schema | effect |
| Sury | sury |
Zod:v3 / v4 / Mini 自动识别
Zod 转换器(packages/xsschema/src/to-json-schema/vendors/zod.ts)是最"聪明"的:它通过检测 _zod 内部属性自动区分 Zod 4 与 Zod 3——v4 走内置 toJSONSchema(显式指定 target: 'draft-7'),v3 则交给 zod-to-json-schema。你混用两版也不用操心。
Valibot 与 ArkType:一行搞定
- Valibot 依赖
@valibot/to-json-schema官方转换器; - ArkType 直接调用其内置的
.toJsonSchema()方法。
官方测试(packages/xsschema/test/to-json-schema.test.ts)对六大库做了快照测试,转换结果均符合 draft-07 规范,例如:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"myString": { "type": "string" },
"myUnion": { "anyOf": [{ "type": "number" }, { "type": "boolean" }] }
},
"required": ["myString", "myUnion"]
}
接入实战:tool() 与 outputFormat 中用它
xsschema 最典型的落点有两个:
🔧 工具输入 Schema:tool() 的 inputSchema 接受原生 Standard JSON Schema 库或纯 JSON Schema;若你的库不支持原生标准,先用 toJsonSchema 转换后再传入,execute 就能拿到已校验的类型化输入。详见 docs/text/tools.md。
📦 结构化输出:generateText 的 outputFormat 接受同样的 Schema 集合,各适配器只保留其协议支持的特性。详见 docs/text/structured-output.md。
const inputSchema = await toJsonSchema(z.object({ city: z.string() }))
常见报错与排查
| 报错特征 | 原因 | 解决 |
|---|---|---|
Missing dependencies "xxx" |
缺少对应库的转换器包 | 按上面依赖表补齐后重试 |
Unsupported schema vendor "xxx" |
该库无原生支持且无转换器 | 换受支持的库,或直接把 JSON Schema 传给 xsAI |
💡 记住:校验不挑库,转换要装包。即使转换失败,validate 对任何 Standard Schema 库都照常可用。
小结
- xsschema 用
toJsonSchema+validate两个 API,统一了 xsAI 生态中 Zod、Valibot、ArkType 等库的 Schema 处理; - 转换优先走原生 Standard JSON Schema,再按 vendor 动态加载转换器,按需付费、树摇友好;
strictJsonSchema帮你收紧结构化输出的边界;- 完整参考请阅读 docs/xsschema.md 与 packages/xsschema/src/index.ts 的导出定义。