佐德呼叫杰森·斯克马

寻找完全相反的(Zod V3)? 检查出来 json-schema- to- zod (韩语)

内容提要

说明: 这是升级到Zod V4的叉子

做它所说的锡; 转换 Zod 计划 V4 进入 JSON 计划虽然佐德 现在在本地支持JSON Schemas有些人还需要更新版的图书馆 所以在这里.

• 支持所有相关的策略类型,基本字符串,数字和数组长度验证和字符串模式.
• 解决内部的递归和反复出现的计划 $ref编号.
• 支持针对遗产的Open API 3.0规格(3.1支持常规Json Schema).
• 支持 Open AI 严格的模式方案(可选对象属性被需要但无效的属性所取代).

Zod 版本兼容性

这个图书馆是 完全兼容 Zod V4 并保持与大多数Zod V3模式的后向兼容.

Zod V4 支持 {}

• 完全兼容 与 Zod V4 新的内部结构
• 错误消息 完全支持 V4 的新错误系统
• 所有验证类型 工作(字符串、数字、对象、阵列、联盟等)
• 元数据和说明 完全支持
• 参考资料处理 为 V4 的系统结构进行了优化

后向兼容性

大多数 Zod V3 代码不会改变 与这个图书馆和Zod V4. 主要例外有:

打破 Zod V3 更改 → V4

一些Zod V3 API在V4中被移除. 以下是变化和如何迁移:

删除字符串方法( 断开)

• ❌ z.string().ip() • 使用 z.string().ipv4() 或者说 z.string().ipv6() 或者说 z.union([z.string().ipv4(), z.string().ipv6()])
• ❌ z.string().cidr() • 使用 z.string().cidrv4() 或者说 z.string().cidrv6()

已贬值但仍得到支持(不突破)

• z.string().email() 偏爱 z.email() (顶级API)
• z.object().strict() 偏爱 z.strictObject()
• z.object().passthrough() 偏爱 z.looseObject()
• z.string().min(5, { message: "..." }) 偏爱 z.string().min(5, { error: "..." })

所有被贬损的方法仍然有效,但可能在未来的Zod版本被去掉.

发起人

非常感谢我们的赞助商! 请考虑通过我的 GitHub 赞助页面每一分钱都有帮助,但这些家伙确实超越了..

将代码审查时间和错误减半( B) 密码兔子.ai

构建 AI 应用程序和工作流程 重装AI工具 retool.com (英语)

使用量

基本实例

import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const mySchema = z
  .object({
    myString: z.string().min(5),
    myUnion: z.union([z.number(), z.boolean()]),
  })
  .describe("My neat object schema");

const jsonSchema = zodToJsonSchema(mySchema, "mySchema");

预期产出

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$ref": "#/definitions/mySchema",
  "definitions": {
    "mySchema": {
      "description": "My neat object schema",
      "type": "object",
      "properties": {
        "myString": {
          "type": "string",
          "minLength": 5
        },
        "myUnion": {
          "type": ["number", "boolean"]
        }
      },
      "additionalProperties": false,
      "required": ["myString", "myUnion"]
    }
  }
}

选项

Schema 名称

可以通过一个字符串作为主zodToJsonSchema函数的第二个参数. 如果您这样做, 您的计画将最终在定义中 对象属性在根上并从中引用 。 或者,你可以通过名称作为 name 选项对象的属性(见下文).

选项对象

而不是计划名称(或无),你可以通过一个选项对象作为第二个参数. 有以下备选方案:

定义

定义选项允许您在定义中手动添加重复的策略,用于更清洁的产出。 它与被命名的"计划",被更改的定义路径和基础路径完全相容. 这里有一个简单的例子:

const myRecurringSchema = z.string();
const myObjectSchema = z.object({ a: myRecurringSchema, b: myRecurringSchema });

const myJsonSchema = zodToJsonSchema(myObjectSchema, {
  definitions: { myRecurringSchema },
});

结果

{
  "type": "object",
  "properties": {
    "a": {
      "$ref": "#/definitions/myRecurringSchema"
    },
    "b": {
      "$ref": "#/definitions/myRecurringSchema"
    }
  },
  "definitions": {
    "myRecurringSchema": {
      "type": "string"
    }
  }
}

错误消息

此特性允许可选地包含通过链条函数创建的错误消息, 要求支持的zod类型 :

// string schema with additional chained function call checks
const EmailSchema = z.string().email("Invalid email").min(5, "Too short");

const jsonSchema = zodToJsonSchema(EmailSchema, { errorMessages: true });

结果

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "format": "email",
  "minLength": 5,
  "errorMessage": {
    "format": "Invalid email",
    "minLength": "Too short"
  }
}

这样可以提供具体字段的、验证步骤的具体错误信息,这些错误信息可用于构建表格。 此格式为 react-hook-form'ajv 解析器(及其) ajv-errors 它用在引擎盖下。 注意如果使用此格式的 AJV 需要 启用 ajv-errors 由于 Vanilla AJV 默认不接受此格式.

自定义错误信件支持

• ZodString 键盘
  • 正则
  • 分钟,最大
  • 电子邮件、 cuid、 uuid、 url
  • 结束于,起于
• Zod 数字
  • 分钟,最大,它,lte,gt,gte,
  • 单位
  • 倍数
• ZodSet 软件
  • 分钟,最大
• 佐德阵列
  • 分钟,最大

其他属性

默认情况下,Zod在解析对象计划时会去除未申报属性. 为了复制此行为的预期输出, ZodToJsonSchema 的默认行为设置 "additionalProperties" 改为 false (虽然这一点的正确性可以辩论). 如果您希望允许未申报的属性,您也可以:

• 设定 removeAdditionalStrategy 改为 "strict"。这将允许任何未以 .strict()。 。 。 .
• 离开 removeAdditionalStrategy 设置为默认值 "passthrough",并添加 .passtrough() {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}去你的物体计划.

删除 additionalProperties 关键词使用 allowedAdditionalProperties 和(或) rejectedAdditionalProperties 选项.

一些计划定义(例如Google Gen AI API)不允许使用 additionalProperties 关键词。 幸运的是, JSON Schema 光谱允许这样做: 留下未定义的关键字 应 其效果与将其设定为真实(如通常的YMMV)相同. 要启用此行为, 请设置选项 allowedAdditionalProperties 改为 undefined。 。 。 .

将关键词排除在外,即使附加属性为 没有 允许,设置 rejectedAdditionalProperties 改为 undefined 还有.

注意 : 如果您的策略被宣布, 以上两个选项将被忽略 .catchall(...) ,因为所提供的计划将被取而代之(如果有效).

预期产出

替换 true 财务报告和审定财务报表 false 页:1 undefined 根据 allowedAdditionalProperties 和(或) rejectedAdditionalProperties 页:1.

override

这个选项需要回调收到Zod schema定义,当前参考对象(包含当前 ref路径和其他选项),一个包含关于wether或未遇到的schema的推导的参数,以及一个强制解析参数.

重要的是: 如果您不想覆盖当前项目, 您必须返回 ignoreOverride 符号从索引导出。 这是因为 undefined 当您想要将财产排除在产生的 JSON 计划之外时, 是返回的有效选项.

import zodToJsonSchema, { ignoreOverride } from "zod-to-json-schema";

zodToJsonSchema(
  z.object({
    ignoreThis: z.string(),
    overrideThis: z.string(),
    removeThis: z.string(),
  }),
  {
    override: (def, refs) => {
      const path = refs.currentPath.join("/");

      if (path === "#/properties/overrideThis") {
        return {
          type: "integer",
        };
      }

      if (path === "#/properties/removeThis") {
        return undefined;
      }

      // Important! Do not return `undefined` or void unless you want to remove the property from the resulting schema completely.
      return ignoreOverride;
    },
  },
);

预期产出:

{
  "type": "object",
  "required": ["ignoreThis", "overrideThis"],
  "properties": {
    "ignoreThis": {
      "type": "string"
    },
    "overrideThis": {
      "type": "integer"
    }
  },
  "additionalProperties": false
}

postProcess

接受所有论据 override 调回, 调回 postProcess callback 也接收生成的 schema. 它应该总是返回 JSON Schema,或 undefined 如果你想过滤出来。 与 override 召回您无需返回 ignoreOverride 如果你对所制作的图案很满意,你只要不改变它.

import zodToJsonSchema, { PostProcessCallback } from "zod-to-json-schema";

// Define the callback to be used to process the output using the PostProcessCallback type:
const postProcess: PostProcessCallback = (
  // The original output produced by the package itself:
  jsonSchema,
  // The ZodSchema def used to produce the original schema:
  def,
  // The refs object containing the current path, passed options, etc.
  refs,
) => {
  if (!jsonSchema) {
    return jsonSchema;
  }

  // Try to expand description as JSON meta:
  if (jsonSchema.description) {
    try {
      jsonSchema = {
        ...jsonSchema,
        ...JSON.parse(jsonSchema.description),
      };
    } catch {}
  }

  // Make all numbers nullable:
  if ("type" in jsonSchema! && jsonSchema.type === "number") {
    jsonSchema.type = ["number", "null"];
  }

  // Add the refs path, just because
  (jsonSchema as any).path = refs.currentPath;

  return jsonSchema;
};

const jsonSchema = zodToJsonSchema(zodSchema, { postProcess });

使用 postProcess 包括实例和其他元a

添加对实例和其他 JSON Schema meta 密钥的支持是该项目最常用的功能。 不幸的是,目前的Zod主(3)对此有相当的厌足支持,因此需要一些用户地黑客. 由于这是一个很常见的用例,我加入了一个帮助器功能,它只是试图将任何描述分析成JSON,并扩展成由此而来的设计.

将您想要添加到输出图中的任意字符串作为描述, 然后导入和使用 jsonDescription 作为程序后选项 :

import zodToJsonSchema, { jsonDescription } from "zod-to-json-schema";

const zodSchema = z.string().describe(
  JSON.stringify({
    title: "My string",
    description: "My description",
    examples: ["Foo", "Bar"],
    whatever: 123,
  }),
);

const jsonSchema = zodToJsonSchema(zodSchema, {
  postProcess: jsonDescription,
});

预期产出:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "title": "My string",
  "description": "My description",
  "examples": ["Foo", "Bar"],
  "whatever": 123
}

移徙指南:Zod V3 → V4

如果你从Zod V3升级到V4,这里需要做的是:

字符串验证更改

IP 地址验证

// ❌ Zod V3 (removed in V4)
z.string().ip();
z.string().ip("v4");
z.string().ip("v6");

// ✅ Zod V4
z.string().ipv4();
z.string().ipv6();
z.union([z.string().ipv4(), z.string().ipv6()]); // for both

CIDR 验证

// ❌ Zod V3 (removed in V4)
z.string().cidr();
z.string().cidr("v4");
z.string().cidr("v6");

// ✅ Zod V4
z.string().cidrv4();
z.string().cidrv6();
z.union([z.string().cidrv4(), z.string().cidrv6()]); // for both

建议: 使用顶级 API

// ✅ Zod V4 preferred (more tree-shakable)
z.email();
z.uuid();
z.url();
z.ipv4();
z.ipv6();

// ⚠️ Still works but deprecated
z.string().email();
z.string().uuid();
z.string().url();
z.string().ipv4();
z.string().ipv6();

对象Schema 更改

// ⚠️ Deprecated but still works
z.object({ name: z.string() }).strict();
z.object({ name: z.string() }).passthrough();

// ✅ Zod V4 preferred
z.strictObject({ name: z.string() });
z.looseObject({ name: z.string() });

错误信件更改

// ⚠️ Deprecated but still works
z.string().min(5, { message: "Too short" });

// ✅ Zod V4 preferred
z.string().min(5, { error: "Too short" });

删除 API 的变通工作

如果您需要支持 IPv4 和 IPv6 (替换旧的) .ip() 方法 :

// Create a reusable IP validator
const ipSchema = z.union([z.string().ipv4(), z.string().ipv6()]);

// Use in your schemas
const serverSchema = z.object({
  host: ipSchema,
  port: z.number(),
});

CIDR 范围:

const cidrSchema = z.union([z.string().cidrv4(), z.string().cidrv6()]);

要意识到的其他更改

UUID 验证为更严格

// Zod V4 is stricter about UUID format
z.string().uuid(); // Now validates against RFC 9562/4122

// For more permissive UUID-like validation:
z.string().guid(); // Accepts any 8-4-4-4-12 hex pattern

基数64URL 无更长时间允许铺设

// Zod V4 base64url is stricter (no padding allowed)
z.string().base64url(); // Must be unpadded

数量验证更改

// Safe integers only
z.number().int(); // Now only accepts safe integers
z.number().safe(); // Deprecated, behaves like .int()

// Recommended: Use the new top-level API
z.int(); // Preferred for integers

删除对象方法

// ❌ Removed in Zod V4
z.object().nonstrict(); // Use z.object() (default behavior)
z.object().deepPartial(); // No direct replacement (was anti-pattern)

// ⚠️ Deprecated but still works
z.object().strip(); // Use z.object() (default behavior)

移徙援助人员

为方便迁移,您可以创建这些辅助函数:

// Helper for IP validation (replaces old .ip() method)
export const ipAddress = () => z.union([z.string().ipv4(), z.string().ipv6()]);

// Helper for CIDR validation (replaces old .cidr() method)
export const cidrRange = () =>
  z.union([z.string().cidrv4(), z.string().cidrv6()]);

// Helper for flexible UUID validation
export const flexibleUuid = () => z.string().guid(); // More permissive than .uuid()

// Usage in your schemas
const networkSchema = z.object({
  serverIp: ipAddress(),
  allowedRange: cidrRange(),
  sessionId: flexibleUuid(),
});

已知问题

• OpenAI目标目前应被视为实验性目标,因为一些选项的组合可能会打破相容性.
• 使用时 .transform,返回类型从提供的函数中推断。 换句话说,返回类型没有计划,无法在运行时转换. 目前JSON schema因此会反映Zod schema的输入侧而不一定反映输出(后一aka. z.infer) (中文(简体) ). 如果这给您的方案造成问题, 请考虑使用效果策略“ 任何” , 它会允许任何类型的输出 .
• JSON Schemas除了对象的字符串之外,不支持任何其他密钥类型. 使用时 z.record 如果有其他密钥类型,则此选项将被忽略。 这个规则的例外是 z.enum 自3.1.1.3起得到支持
• 相对 JSON 指针, 同时发布 JSON计划草案 2020-12,在技术上不是它的一部分。 目前,大多数解决者根本不处理它们.
• 自 v3 起, 对象解析器使用 .isOptional() 检查是否应将财产列入 required 或无. 这有潜在的危险行为 呼叫 .safeParse 与 undefined工作围绕,确保你 preprocess 和其他效果的回调是纯的,不会产生错误。 在Zod Repo中记录了一个问题,可以 追踪到这里。 。 。 .
• JSON Schema 2020-12版本尚未被官方支持. 然而,您应该能够使用此库来获取2020-12年格式的相容计划,只需更改返回的计划 $schema 字段改为:“https://json-schema.org/draft/2020-12/schema#”

版本

这个包 没有 跟着语义版本。 这套软件包的主要版本和次要版本反映了与软件包的特征均等 Zod 软件包。 。 。 .

我将尽力将API突破式的改变保持在绝对最低,但新的特征可能出现为"patches",比如在3.9.1中引入了选项模式.

更改日志

https://github.com/StefanTerdell/zod-to-json-schema/blob/master/changelog.md 互联网档案馆的存檔,存档日期2014-12-21