# @gcornut/valibot-json-schema 中文文档

规范地址：https://npmcn.com/package/%40gcornut/valibot-json-schema/

版本：0\.42\.0
npm 元数据更新时间：2024-09-16T16:50:16.653Z
中文译文更新时间：2026-11-16T00:51:56.778Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gcornut/valibot-json-schema
原文对照：https://npmcn.com/package/%40gcornut/valibot-json-schema/?lang=original
项目主页：https://github.com/gcornut/valibot-json-schema#readme
源码仓库：https://github.com/gcornut/valibot-json-schema

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：226 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2023-10-15T10:01:06.641Z
- 最新版本发布：2024-09-16T16:50:16.236Z
- 近 30 天下载量：130167（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：77（近 12 个月 0 个）

## 中文简介

> \[! \] 由于瓦利博特现在有 官方的JSON 计划转换器 [@valibot/to-json-schema (英语)](https://github.com/fabian-hiller/valibot/tree/main/packages/to-json-schema)。 > 命令行接口被移动到 p

## 安装

```sh
npm install @gcornut/valibot-json-schema
```

也可以使用：`pnpm add @gcornut/valibot-json-schema`、`yarn add @gcornut/valibot-json-schema`、`bun add @gcornut/valibot-json-schema`

## README

> \[叹息\] 由于瓦利博特现在有 官方的JSON 计划转换器 [@valibot/to-json-schema (英语)](https://github.com/fabian-hiller/valibot/tree/main/packages/to-json-schema)。 。 。 . 命令行接口被移动到工程中 [@gcornut/cli-valibot-to-json-schema (英语)](https://github.com/gcornut/cli-valibot-to-json-schema)。 。 。 .

# 校对:soup

CLI 和 JS 转换工具 [维利博特](https://valibot.dev/) jSON计划(07草案).

瓦利博特的一些特征不能被转换为JSON schema. JS特定类型 `blob` 或者说 `nan` 很明显 不能有一个等同的.  
[见支持的特性](https://npmcn.com/package/%40gcornut/valibot-json-schema/#readme-supported-features) 需要更多信息.

## 命令行工具

这个 lib 输出一个 CLI, 可以用来快速将定义 valibot schemas 的 JSON schema 转换为 JSON schema.

```shell
# Convert valibot schemas to JSON schema
npx @gcornut/valibot-json-schema to-json-schema ./schemas.js
```

这输出了将 Valibot schemas 转换为 JSON schema. 如果默认导出为 Valibot 计划, 它就是 用作 根定义。 其它输出的 Valibot 计划转换为 JSON 计划 `definitions` 节.

**见详细输入和输出:**

_输入文件 `./schemas.js`_数字 :

```js
import * as v from 'valibot';

export const AString = v.string();
const AnObject = v.object({ aString: AString });
export default AnObject;
```

_产出转换_数字 :

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "AString": {
      "type": "string"
    }
  },
  "properties": {
    "aString": {
      "$ref": "#/definitions/AString"
    }
  },
  "required": [
    "aString"
  ],
  "type": "object"
}
```

`AnObject` 是源模块中的默认导出,因此转换为根定义. `AString` 导出 单独输出到 `definitions` 节.

### 无害环境管理和类型脚本输入模块

这个 `valibot-json-schema` CLI 使用 JS 模块加载输入 **标准节点JS 普通JS 需要**这意味着你会 有问题与 **无害环境管理或类型脚本模块**。 。 。 .

为了补救,你要么要先安装 `ebuild-runner` 财务报告和审定财务报表 `esbuild` (以便程序能够使用它们)或 使用支持这些模块的节点兼容运行时间( 如: bun, 替换) `npx` 与 `bunx`) (中文(简体) ).

示例

```shell
# Convert from TS/ESM module using bunx
bunx @gcornut/valibot-json-schema to-json-schema ./schemas.ts

# Convert from TS/ESM module with esbuild-runner preinstalled
npm install esbuild esbuild-runner
npx @gcornut/valibot-json-schema to-json-schema ./schemas.ts

# Convert from TS/ESM module using `yarn dlx` multi-package feature 
yarn dlx -p esbuild -p esbuild-runner -p @gcornut/valibot-json-schema valibot-json-schema to-json-schema ./schemas.ts
```

### CLI 参数

使用 `-o <file>` 选项将 JSON 计划输出到一个文件而不是 `stdout`。 。 。 .

使用 `-t <type>` 从模块导出(默认为“默认”导出)中选择根定义. 示例 `-t foo.bar` 会得到财产 `bar` 编辑 `foo` 输入的 JS 模块.

使用 `-d <type>` 选项从模块导出中选择定义(而不是使用所有非默认导出). 示例 `-d foo.bar` 会得到财产 `bar` 编辑 `foo` 输入的 JS 模块.

见 [高级选项](https://npmcn.com/package/%40gcornut/valibot-json-schema/#readme-advanded-options) 更多选择.

## 程序用途

使用 `toJSONSchema` 函数将 Valibot schema 转换为 JSON schema (v7) :

```js
import { toJSONSchema } from '@gcornut/valibot-json-schema';
import { string } from 'valibot';

toJSONSchema({ schema: string() })
// {
//    $schema: 'http://json-schema.org/draft-07/schema#',
//    type: 'string',
// }
```

如果你有许多命名的策略要转换,你可以使用 `definitions` 选项计划将它列为普通对象,以便 计划名称(对象键)和计划定义(对象值)都导出到 JSON schema.

```js
import { toJSONSchema } from '@gcornut/valibot-json-schema';
import { number } from 'valibot';

const Number = number();
toJSONSchema({ definitions: { Number } });
// {
//    $schema: 'http://json-schema.org/draft-07/schema#',
//    definitions: { Number: { type: 'number' } },
// }
```

见 [高级选项](https://npmcn.com/package/%40gcornut/valibot-json-schema/#readme-advanded-options) 更多选择.

## 高级选项

### 严格对象类型

使用 `strictObjectTypes` 选项(`--strictObjectTypes` 在 CLI 中,可以强制所有未知对象类型块 键`additionalProperties: false`) (中文(简体) ).

### 忽略未知的验证

你也许想要在你的Valibot计划中得到高级验证,JSON计划不能支持( 喜欢 [习惯( )](https://valibot.dev/api/custom/)) (中文(简体) ). 默认, `toJSONSchema()` 将犯错误,以便你们知道 这些不能转换成JSON计划.

使用 `ignoreUnknownValidation` 选项(`--ignoreUnknownValidation` 在 CLI 中,您可以忽略未支持的 valibot 论证.

如果您宁愿忽略特定类型的验证, 您可以 使用情况 [页:1 `customValidationConversion` 选项](https://npmcn.com/package/%40gcornut/valibot-json-schema/#readme-custom-validation-conversion)。 。 。 .

### 共同类型的战略

许多联署材料类型在JSON和 `toJSONSchema()` 将遇到一个错误 这些 然而,其中一些类型有共同的转换策略.

使用 `dateStrategy` 选项(`--dateStrategy` 在CLI中,您可以选择将 JS Date 对象转换为字符串( 与 `date-time` 格式)或为整数(带有 `unix-time` 页:1.

使用 `undefinedStrategy` 选项(`--undefinedStrategy` 在CLI中,您可以选择转换 `undefined` 改为: " 任何“计划”(无验证)或 `null` 类型.

使用 `bigintStrategy` 选项(`--bigintStrategy` 在CLI中,您可以选择将 JS BigInt 值转换为 整数( 有 `int64` 格式)或输入字符串.

### 自定义计划转换

在某些情况下,您可能想要提供自定义的 schema 转换以覆盖标准 schema 转换或添加 转换不支持的策略.

使用 `customSchemaConversion` 选项,您可以为任何valibot schema类型提供自定义的 schema 转换器.

**示例**: 将 JS Set 计划转换为数组计划

```js
import { set, string } from 'valibot';

toJSONSchema({
    schema: set(string()),
    customSchemaConversion: {
        // Treat set type like an array
        set: (schema, converter) => converter(array(schema.value))
    },
})
// => { type: 'array', items: { type: 'string' } }
```

### 自定义验证转换

使用 `customValidationConversion` 选项,您可以为任何 valibot 提供自定义验证转换器 验证类型.

**示例**: 忽略阴道 `custom()` 在所有字符串计划中验证

```ts
import { string, custom, pipe } from 'valibot';

toJSONSchema({
    schema: pipe(string(), custom(myCustomStringValidation)),
    customValidationConversion: {
        string: { custom: () => ({}) }
    },
})
// => { type: 'string' }
```

## 支持的特性

一些被转换的 schema 可能在 JSON 的 schema 校验器中行为略有不同, 特别是在字符串上 格式 (单位:千美元)`email`, (中文(简体) ), `ipv4`, (中文(简体) ), `date`因为它们的执行不同于活字节的执行.

以下是支持的 Valibot 特性列表( 有些有部分支持):

| 特性 | 状态 |
| --- | --- |
| `any` 计划 | 获得支持 |
| `null` 计划 | 获得支持 |
| `number` 计划 | 获得支持 |
| `bigint` 计划 | \* 与 `bigintStrategy` 选项 |
| `string` 计划 | 获得支持 |
| `boolean` 计划 | 获得支持 |
| `literal` 计划 | QQ 部分: 仅支持 JSON 兼容的文字 |
| `nullable` 计划 | 获得支持 |
| `nullish` 计划 | 获得支持 |
| `optional` 计划 | 获得支持 |
| `never` 计划 | qq 部分:仅在内部 `object` 休养或 `tuple` 剩余参数 |
| `picklist` 计划 | QQ 部分: 仅支持 JSON 兼容的文字 |
| `enum_` 计划 | 获得支持 |
| `union` 计划 | 获得支持 |
| `variant` 计划 | 部分: 转换就像一个 `union` |
| `intersect` 计划 | 获得支持 |
| `array` 计划 | 获得支持 |
| `tuple` 计划 | 获得支持 |
| `object` 计划 | 获得支持 |
| `record` 计划 | qq 部分: 只允许字符串密钥, 仅适用于普通对象, 而非数组 |
| `lazy` 计划 | qq 部分: 只有在内部设置时 [引用于 `definitions`](https://npmcn.com/package/%40gcornut/valibot-json-schema/#readme-json-schema-definitions) |
| `date` 计划 | \* 与 `dateStrategy` 选项 |
| `length` 验证 | 获得支持 |
| `maxLength` 验证 | 获得支持 |
| `minLength` 验证 | 获得支持 |
| `regex` 验证 | QQ 部分: 仅针对 JSON schema 支持的 RegExp 特性 |
| `value` 验证 | qq 部分:仅限 `string`, (中文(简体) ), `number` 财务报告和审定财务报表 `boolean` |
| `minValue` 验证 | qq 部分:仅限 `number` |
| `maxValue` 验证 | qq 部分:仅限 `number` |
| `multipleOf` 验证 | 获得支持 |
| `integer` 验证 | 获得支持 |
| `email` 验证 | QQ 支持( JSON 计划格式) |
| `isoDate` 验证 | QQ 支持( JSON 计划格式) |
| `isoTimestamp` 验证 | QQ 支持( JSON 计划格式) |
| `ipv4` 验证 | QQ 支持( JSON 计划格式) |
| `ipv6` 验证 | QQ 支持( JSON 计划格式) |
| `uuid` 验证 | QQ 支持( JSON 计划格式) |
| `description` 元数据 | 获得支持 |

## 常见问题

### @gcornut/valibot-json-schema 是什么？

\[\! \] 由于瓦利博特现在有 官方的JSON 计划转换器 @valibot/to-json-schema \(英语\)。 \> 命令行接口被移动到 p

### 如何安装 @gcornut/valibot-json-schema？

在项目目录运行 npm install @gcornut/valibot-json-schema，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 valibot-json-schema，可以用 npx valibot-json-schema 直接运行。

### @gcornut/valibot-json-schema 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gcornut/valibot-json-schema 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gcornut/valibot-json-schema 可以商用吗？

@gcornut/valibot-json-schema 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @gcornut/valibot-json-schema 的下载量有多少？

根据 npm 官方下载统计，@gcornut/valibot-json-schema 在 2026/10/16 – 2026/11/14 这 30 天内被下载 130,167 次，日均约 4,339 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gcornut/valibot-json-schema 还在维护吗？

最新版本 0\.42\.0 发布于 2024/09/17（2 年前）；至今共发布 77 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/10/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

