zod

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zod

Specification

规范

The words

MUST

MUST NOT

REQUIRED

SHALL

SHALL NOT

SHOULD

SHOULD NOT

RECOMMENDED

MAY

, and

OPTIONAL

are interpreted as described in RFC 2119.

Use this skill to design or review Zod schemas.

Default to
```
zod/mini
```
for new work.
Preserve an existing classic
```
zod
```
surface when the file or repo already established it.
Read references/variant-guide.md when the import or API surface is unclear, or when you need the exact mini-vs-classic rules.
Read references/patterns.md for compact
```
zod/mini
```
-first examples.

文中的

MUST

、

MUST NOT

、

REQUIRED

、

SHALL

、

SHALL NOT

、

SHOULD

、

SHOULD NOT

、

RECOMMENDED

、

MAY

和

OPTIONAL

术语，均按照RFC 2119中的定义进行解释。

使用本技能来设计或审核Zod schema。

新开发默认使用
```
zod/mini
```
。
当文件或代码库已采用经典
```
zod
```
接口时，保留现有接口。
当导入或API接口不明确，或需要了解
```
zod/mini
```
与经典
```
zod
```
的具体规则时，请阅读references/variant-guide.md。
如需
```
zod/mini
```
优先的简洁示例，请阅读references/patterns.md。

Workflow

工作流程

Detect the local surface.

bash

rg -n "from 'zod/mini'|from \"zod/mini\"|from 'zod'|from \"zod\"" .
rg -n '"zod"' package.json bun.lock pnpm-lock.yaml package-lock.json yarn.lock

Stay on the file or repo's established surface.
If none exists, start with
```
import * as z from 'zod/mini'
```
.
Do not migrate between
```
zod
```
and
```
zod/mini
```
unless the user explicitly asks.

Define the boundary.

Parse untrusted input at I/O boundaries.
Use
```
safeParse
```
for expected invalid input.
Use
```
parse
```
when invalid input should throw.

Choose exact contract semantics.

Prefer
```
z.strictObject(...)
```
for internal contracts.
Use
```
z.looseObject(...)
```
only when extra keys are intentional.
Choose
```
optional
```
,
```
nullable
```
,
```
null
```
, and
```
undefined
```
explicitly.

Compose.

Prefer base schemas plus
```
intersection
```
,
```
union
```
, and literal tags.
Use
```
lazy
```
for recursion.
Keep
```
custom
```
, manual
```
any
```
, and similar escape hatches narrow.

Normalize only when useful.

Normalize messy raw values before parsing the narrower schema the caller needs.
Re-parse at the consumption boundary only when that local contract is stricter than the upstream payload contract.

Check serialization boundaries.

Keep returned, stored, and transmitted payloads data-only.
Keep functions, helper objects, closures, and other behavior-bearing values local.

检测本地接口。

bash

rg -n "from 'zod/mini'|from \"zod/mini\"|from 'zod'|from \"zod\"" .
rg -n '"zod"' package.json bun.lock pnpm-lock.yaml package-lock.json yarn.lock

遵循文件或代码库已确立的接口。
若尚未确立，则从
```
import * as z from 'zod/mini'
```
开始。
除非用户明确要求，否则不要在
```
zod
```
与
```
zod/mini
```
之间迁移。

定义边界。

在I/O边界处解析不可信输入。
对于预期的无效输入，使用
```
safeParse
```
。
当无效输入应抛出异常时，使用
```
parse
```
。

选择精确的契约语义。

内部契约优先使用
```
z.strictObject(...)
```
。
仅当需要保留额外键时，才使用
```
z.looseObject(...)
```
。
明确选择
```
optional
```
、
```
nullable
```
、
```
null
```
和
```
undefined
```
类型。

组合schema。

优先使用基础schema结合
```
intersection
```
、
```
union
```
和字面量标签。
使用
```
lazy
```
处理递归。
尽量缩小
```
custom
```
、手动
```
any
```
等逃逸机制的使用范围。

仅在必要时进行规范化。

在解析调用方所需的更窄schema之前，先规范化杂乱的原始值。
仅当本地契约比上游负载契约更严格时，才在消费边界处重新解析。

检查序列化边界。

确保返回、存储和传输的负载仅包含数据。
将函数、辅助对象、闭包及其他带有行为的对象保留在本地。

Rules

规则

Treat Zod as a runtime contract system, not just a typing tool.
Prefer composition over mutation-style schema building.
Prefer readable operational errors over raw issue dumps.

将Zod视为运行时契约系统，而非仅作为类型工具。
优先使用组合式schema构建，而非变异式。
优先提供可读性强的操作错误，而非原始的问题转储。