xsAI生态中的Schema统一:xsschema转换与校验完全指南(Zod、Valibot、ArkType)

原创2026-11-06 23:23:561,877 阅读

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):

  1. 先查原生支持:如果 Schema 暴露了 ~standard.jsonSchema,直接以 draft-07 为目标取输入 Schema,不加载任何额外依赖;
  2. 再按 vendor 加载转换器:否则根据 ~standard.vendor 动态 import 对应库的转换器(实现见 packages/xsschema/src/to-json-schema/vendors/index.ts);
  3. 依赖缺失即报错:转换器包没装或库无法表达时,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 的导出定义。
登录后查看全文
xsai