@gcornut/valibot-json-schema

中文文档
0.42.0发布于 2024/09/17TypeScriptESM + CJS构建来源已验证近 30 天下载 13万

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

中文使用文档
文档目录11 节
  1. 命令行工具
  2. 无害环境管理和类型脚本输入模块
  3. CLI 参数
  4. 程序用途
  5. 高级选项
  6. 严格对象类型
  7. 忽略未知的验证
  8. 共同类型的战略
  9. 自定义计划转换
  10. 自定义验证转换
  11. 支持的特性

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

校对:soup

CLI 和 JS 转换工具 维利博特 jSON计划(07草案).

瓦利博特的一些特征不能被转换为JSON schema. JS特定类型 blob 或者说 nan 很明显 不能有一个等同的.
见支持的特性 需要更多信息.

命令行工具

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

# 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数字 :

import * as v from 'valibot';

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

产出转换数字 :

{
  "$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) (中文(简体) ).

示例

# 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 模块.

见 高级选项 更多选择.

程序用途

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

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.

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' } },
// }

见 高级选项 更多选择.

高级选项

严格对象类型

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

忽略未知的验证

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

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

如果您宁愿忽略特定类型的验证, 您可以 使用情况 页:1 customValidationConversion 选项。 。 。 .

共同类型的战略

许多联署材料类型在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 计划转换为数组计划

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() 在所有字符串计划中验证

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
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 共发布 77 个版本,首次发布于 2023/10/15;过去 12 个月发布了 0 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.42.0latest2024/09/172 年前
0.41.2-snapshot.2snapshot2024/09/172 年前
0.41.2-snapshot.12024/09/172 年前
0.41.2-snapshot.02024/09/172 年前
0.41.12024/09/062 年前
0.41.1-snapshot.22024/09/052 年前

其他发布通道:alpha → 0.0.27-alpha.0,prerelease → 0.0.28-rc.3,snapshot → 0.41.2-snapshot.2。

关于 @gcornut/valibot-json-schema 的常见问题

@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 和提交记录判断。