后端【免费下载链接】arktypeTypeScripts 1:1 validator, optimized from editor to runtime项目地址https://gitcode.com/gh_mirrors/ar/arktype点击查看免费下载本文是一份关于 ArkType 官方包ark/json-schema的实战指南。它面向当前代码库中已使用 JSON Schema 进行运行时校验、希望平滑迁移到 ArkType 的开发者也面向希望将 ArkType 类型反向导出为 JSON Schema 的开发者。读完本文你将掌握jsonSchemaToType()的完整用法与支持范围、Type.toJsonSchema()的反向转换方式以及如何在编译期校验 JSON Schema 定义的正确性包括字符串 Schema 的特例。什么是ark/json-schemaark/json-schema是 ArkType 官方仓库中独立发布的子包当前版本 0.0.9见 ark/json-schema/package.json它的核心使命只有一个把 JSON Schema 描述转换为 ArkType 的Type。这解决了 ArkType 采纳路径上的一个真实痛点很多存量代码库的运行时校验体系是基于 JSON Schema 搭建的例如 OpenAPI 文档、数据库校验层、消息契约等。有了这个转换器这些团队无需重写全部校验描述就可以直接在 ArkType 上继续开发并逐步获得 ArkType 的编辑器内类型推断与更精细的错误信息。最基础的用法只有一行import { jsonSchemaToType } from ark/json-schema const T jsonSchemaToType({ type: string, minLength: 5, maxLength: 10 })它与下面的 ArkType 原生写法完全等价import { type } from arktype const T type(5string10)也就是说jsonSchemaToType把一个 JSON Schema 对象翻译成了等价的 ArkType 类型后续你可以像使用任何 ArkType 类型一样对T调用.assert()、.allows()、.narrow()等全部 API。包结构一次完整的翻译管线从源码结构看ark/json-schema的入口 ark/json-schema/index.ts 只导出三样东西jsonSchemaToType、JsonSchemaScope与错误类型。真正的主流程位于 ark/json-schema/json.ts若输入是布尔值true/false直接映射为type.any/type.never——对应 JSON Schema 中布尔简写式的语义若输入是数组则视为anyOf列表否则先解析公共关键字const/enum与组合关键字allOf/anyOf/oneOf/not若存在type关键字则按类型分派到对应的专用解析器array、boolean|null、integer|number、object、string以及unknown[]JSON Schema 允许type为类型数组的写法将专用解析器结果与公共/组合解析结果用and()求交合并若type不在支持列表内抛出UnsupportedType错误若没有任何有效关键字抛出InsufficientKeys错误提示至少需要type、enum、const、allOf、anyOf、oneOf、not之一错误文案见 ark/json-schema/errors.ts。每个类型的专用解析器在源码中都是独立文件方便读者按需查阅映射细节JSON Schema 输入对应源码映射到的 ArkType 约束stringark/json-schema/string.tsdomain: stringminLength/maxLength映射为长度约束pattern映射为正则约束number/integerark/json-schema/number.tsmin/max含exclusive*边界、multipleOf映射为divisorinteger自动补divisor: 1arrayark/json-schema/array.tsitems/prefixItems/additionalItems映射为sequenceminItems/maxItems映射为长度约束uniqueItems/contains映射为自定义 predicateobjectark/json-schema/object.tsproperties/required映射为 required/optional 键patternProperties映射为索引签名propertyNames/additionalProperties/minProperties/maxProperties均有对应实现const/enumark/json-schema/common.tstype.unit(...)/type.enumerated(...)二者同时出现时报错allOf/anyOf/oneOf/notark/json-schema/composition.ts分别映射为and()、or()、自定义恰好一个匹配校验器、not取反校验器编译期校验把Schema 本身也变成类型ark/json-schema还提供了额外的类型安全保障——Schema 定义本身可以在编译期被静态检查。你只需要引入arktype导出的JsonSchema命名空间类型import type { JsonSchema } from arktype const integerSchema: JsonSchema.Numeric { type: integer, multipleOf: 3 // 类型错误multipleOf 必须是 number }这里multipleOf: 3会立即触发编译错误因为JsonSchema.Numeric精确描述了数字 Schema 的合法结构。类似的JsonSchema.Array、JsonSchema.Object、JsonSchema.String等子类型也都可用它们由 ArkType 自身以类型驱动的方式定义对应 ark/schema/shared/jsonSchema.ts 等类型声明。需要特别注意的是字符串 Schema 必须从ark/json-schema导入类型而不能使用arktype的JsonSchema.String。原因在 ark/json-schema/scope.ts 的源码注释中写得很清楚ark/json-schema尚未支持format关键字而 ArkType 内置的JsonSchema.String包含format同时本包为了灵活性将pattern放宽为string | RegExp。因此包内自定义了StringSchema类型import type { StringSchema } from ark/json-schema const stringSchema: StringSchema { type: string, minLength: 3 // 类型错误minLength 必须是 number }正确写法是minLength: 3。如果你需要format如format: email约束请在字符串场景下回退到arktype自带的类型体系或者自行用 ArkType 的pattern表达。反向转换toJsonSchema()是内置能力需要强调的是把 ArkType 类型转成 JSON Schema并不需要这个包。每个 ArkTypeType都自带toJsonSchema()方法import { type } from arktype // { type: string, minLength: 5, maxLength: 10 } const schema type(5string10).toJsonSchema()ark/json-schema只负责JSON Schema → ArkType这一单向转换反向路径由 ArkType 核心提供。其实现位于 ark/schema/shared/toJsonSchema.ts默认以draft-2020-12dialecthttps://json-schema.org/draft/2020-12/schema为目标并支持useRefs、target等配置选项。要注意的是toJsonSchema()并非对所有类型都可行——遇到 morph、predicate、特定 proto、date、pattern 求交等无法 JSON 化的场景会抛出ToJsonSchemaError带arrayObject、morph、predicate、date等错误码因此建议在转换前确认你的类型集合都在可 JSON 化范围内。已知限制根据 ark/json-schema/README.md 与源码当前版本0.0.9存在以下明确限制迁移前请先对照检查不支持dependencies关键字对象属性间条件依赖不支持if/else/then条件组合multipleOf仅支持整数JSON Schema 规范允许任意 number但 ArkType 的divisor约束只接受整数转换时请注意integer类型会自动获得divisor: 1。此外从源码可推断出两个隐含行为数组 Schema 中prefixItems与items/additionalItems的组合、数字 Schema 中maximum与exclusiveMaximum同时出现等规范上互斥的写法都会在运行时抛出对应的TraversalError错误消息集中在 ark/json-schema/errors.ts例如Provided number JSON Schema cannot have maximum and exclusiveMaximum而patternProperties之间的重叠兼容性目前不做校验正则求交本质困难源码注释对此有明确说明。用测试验证转换语义仓库自带了一套基于ark/attest的测试ark/json-schema/tests/ 等既能当文档读也能验证你理解的转换语义import { attest, contextualize } from ark/attest import { jsonSchemaToType } from ark/json-schema contextualize(() { it(allOf, () { const tAllOf jsonSchemaToType({ allOf: [ { type: string, minLength: 1 }, { type: string, maxLength: 10 } ] }) attest(tAllOf.expression).snap(string 10 1) }) it(not, () { const tNot jsonSchemaToType({ not: { type: string, maxLength: 3 } }) attest(tNot.allows(123)).equals(true) attest(() tNot.assert(123)).throws( TraversalError: must be not: a string and at most length 3 (was 123) ) }) it(oneOf, () { const tOneOf jsonSchemaToType({ oneOf: [{ type: string, minLength: 10 }, { const: foo }] }) attest(tOneOf.allows(foo)).equals(true) attest(() tOneOf.assert(bar)).throws( TraversalError: must be valid according to jsonSchemaOneOfValidator (was bar) ) }) })这些断言同时揭示了实现细节allOf被折叠为 ArkType 的交集表达式not与oneOf则被实现为带名字的运行时 predicate类型 JSON 中会显示为$ark.jsonSchemaNotValidator、$ark.jsonSchemaOneOfValidator运行时的失败信息会精确描述必须恰好满足其中一个还是必须不满足某个子 Schema。总结迁移方向JSON Schema → ArkType使用ark/json-schema的jsonSchemaToType()支持string/number/integer/boolean/null/array/object及各组合关键字、const/enum能直接替换存量 JSON Schema 校验器导出方向ArkType → JSON Schema直接使用Type.toJsonSchema()无需额外包默认输出 draft-2020-12定义期类型安全用JsonSchema.*类型标注 Schema 对象即可获得编译期校验字符串 Schema 记得从ark/json-schema导入StringSchema迁移前自查确认没有使用dependencies、if/else/then且multipleOf均为整数。赞分享后端【免费下载链接】arktypeTypeScripts 1:1 validator, optimized from editor to runtime项目地址https://gitcode.com/gh_mirrors/ar/arktype点击查看免费下载相关推荐Trigger.dev schema-to-json 指南把 Zod、Yup、ArkType、Effect、TypeBox 统一转换为 JSON SchemaTrigger.dev schema to json 指南把 Zod、Yup、ArkType、Effect、TypeBox 统一转换为 JSON SchemaAI Agent后端任务调度开发工具可观测性AI 应用io-ts与JSON Schema如何将运行时类型转换为JSON Schema定义io ts与JSON Schema如何将运行时类型转换为JSON Schema定义 想要在TypeScript项目中实现运行时类型安全同时生成标准的JSON后端强大的 TypeScript 到 JSON Schema 转换器ts-json-schema-generator强大的 TypeScript 到 JSON Schema 转换器ts json schema generator 在软件开发中JSON Schema 是一种开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ArkType JSON Schema 互操作指南：`@ark/json-schema` 的 Schema 转换与类型安全
后端【免费下载链接】arktypeTypeScripts 1:1 validator, optimized from editor to runtime项目地址https://gitcode.com/gh_mirrors/ar/arktype点击查看免费下载本文是一份关于 ArkType 官方包ark/json-schema的实战指南。它面向当前代码库中已使用 JSON Schema 进行运行时校验、希望平滑迁移到 ArkType 的开发者也面向希望将 ArkType 类型反向导出为 JSON Schema 的开发者。读完本文你将掌握jsonSchemaToType()的完整用法与支持范围、Type.toJsonSchema()的反向转换方式以及如何在编译期校验 JSON Schema 定义的正确性包括字符串 Schema 的特例。什么是ark/json-schemaark/json-schema是 ArkType 官方仓库中独立发布的子包当前版本 0.0.9见 ark/json-schema/package.json它的核心使命只有一个把 JSON Schema 描述转换为 ArkType 的Type。这解决了 ArkType 采纳路径上的一个真实痛点很多存量代码库的运行时校验体系是基于 JSON Schema 搭建的例如 OpenAPI 文档、数据库校验层、消息契约等。有了这个转换器这些团队无需重写全部校验描述就可以直接在 ArkType 上继续开发并逐步获得 ArkType 的编辑器内类型推断与更精细的错误信息。最基础的用法只有一行import { jsonSchemaToType } from ark/json-schema const T jsonSchemaToType({ type: string, minLength: 5, maxLength: 10 })它与下面的 ArkType 原生写法完全等价import { type } from arktype const T type(5string10)也就是说jsonSchemaToType把一个 JSON Schema 对象翻译成了等价的 ArkType 类型后续你可以像使用任何 ArkType 类型一样对T调用.assert()、.allows()、.narrow()等全部 API。包结构一次完整的翻译管线从源码结构看ark/json-schema的入口 ark/json-schema/index.ts 只导出三样东西jsonSchemaToType、JsonSchemaScope与错误类型。真正的主流程位于 ark/json-schema/json.ts若输入是布尔值true/false直接映射为type.any/type.never——对应 JSON Schema 中布尔简写式的语义若输入是数组则视为anyOf列表否则先解析公共关键字const/enum与组合关键字allOf/anyOf/oneOf/not若存在type关键字则按类型分派到对应的专用解析器array、boolean|null、integer|number、object、string以及unknown[]JSON Schema 允许type为类型数组的写法将专用解析器结果与公共/组合解析结果用and()求交合并若type不在支持列表内抛出UnsupportedType错误若没有任何有效关键字抛出InsufficientKeys错误提示至少需要type、enum、const、allOf、anyOf、oneOf、not之一错误文案见 ark/json-schema/errors.ts。每个类型的专用解析器在源码中都是独立文件方便读者按需查阅映射细节JSON Schema 输入对应源码映射到的 ArkType 约束stringark/json-schema/string.tsdomain: stringminLength/maxLength映射为长度约束pattern映射为正则约束number/integerark/json-schema/number.tsmin/max含exclusive*边界、multipleOf映射为divisorinteger自动补divisor: 1arrayark/json-schema/array.tsitems/prefixItems/additionalItems映射为sequenceminItems/maxItems映射为长度约束uniqueItems/contains映射为自定义 predicateobjectark/json-schema/object.tsproperties/required映射为 required/optional 键patternProperties映射为索引签名propertyNames/additionalProperties/minProperties/maxProperties均有对应实现const/enumark/json-schema/common.tstype.unit(...)/type.enumerated(...)二者同时出现时报错allOf/anyOf/oneOf/notark/json-schema/composition.ts分别映射为and()、or()、自定义恰好一个匹配校验器、not取反校验器编译期校验把Schema 本身也变成类型ark/json-schema还提供了额外的类型安全保障——Schema 定义本身可以在编译期被静态检查。你只需要引入arktype导出的JsonSchema命名空间类型import type { JsonSchema } from arktype const integerSchema: JsonSchema.Numeric { type: integer, multipleOf: 3 // 类型错误multipleOf 必须是 number }这里multipleOf: 3会立即触发编译错误因为JsonSchema.Numeric精确描述了数字 Schema 的合法结构。类似的JsonSchema.Array、JsonSchema.Object、JsonSchema.String等子类型也都可用它们由 ArkType 自身以类型驱动的方式定义对应 ark/schema/shared/jsonSchema.ts 等类型声明。需要特别注意的是字符串 Schema 必须从ark/json-schema导入类型而不能使用arktype的JsonSchema.String。原因在 ark/json-schema/scope.ts 的源码注释中写得很清楚ark/json-schema尚未支持format关键字而 ArkType 内置的JsonSchema.String包含format同时本包为了灵活性将pattern放宽为string | RegExp。因此包内自定义了StringSchema类型import type { StringSchema } from ark/json-schema const stringSchema: StringSchema { type: string, minLength: 3 // 类型错误minLength 必须是 number }正确写法是minLength: 3。如果你需要format如format: email约束请在字符串场景下回退到arktype自带的类型体系或者自行用 ArkType 的pattern表达。反向转换toJsonSchema()是内置能力需要强调的是把 ArkType 类型转成 JSON Schema并不需要这个包。每个 ArkTypeType都自带toJsonSchema()方法import { type } from arktype // { type: string, minLength: 5, maxLength: 10 } const schema type(5string10).toJsonSchema()ark/json-schema只负责JSON Schema → ArkType这一单向转换反向路径由 ArkType 核心提供。其实现位于 ark/schema/shared/toJsonSchema.ts默认以draft-2020-12dialecthttps://json-schema.org/draft/2020-12/schema为目标并支持useRefs、target等配置选项。要注意的是toJsonSchema()并非对所有类型都可行——遇到 morph、predicate、特定 proto、date、pattern 求交等无法 JSON 化的场景会抛出ToJsonSchemaError带arrayObject、morph、predicate、date等错误码因此建议在转换前确认你的类型集合都在可 JSON 化范围内。已知限制根据 ark/json-schema/README.md 与源码当前版本0.0.9存在以下明确限制迁移前请先对照检查不支持dependencies关键字对象属性间条件依赖不支持if/else/then条件组合multipleOf仅支持整数JSON Schema 规范允许任意 number但 ArkType 的divisor约束只接受整数转换时请注意integer类型会自动获得divisor: 1。此外从源码可推断出两个隐含行为数组 Schema 中prefixItems与items/additionalItems的组合、数字 Schema 中maximum与exclusiveMaximum同时出现等规范上互斥的写法都会在运行时抛出对应的TraversalError错误消息集中在 ark/json-schema/errors.ts例如Provided number JSON Schema cannot have maximum and exclusiveMaximum而patternProperties之间的重叠兼容性目前不做校验正则求交本质困难源码注释对此有明确说明。用测试验证转换语义仓库自带了一套基于ark/attest的测试ark/json-schema/tests/ 等既能当文档读也能验证你理解的转换语义import { attest, contextualize } from ark/attest import { jsonSchemaToType } from ark/json-schema contextualize(() { it(allOf, () { const tAllOf jsonSchemaToType({ allOf: [ { type: string, minLength: 1 }, { type: string, maxLength: 10 } ] }) attest(tAllOf.expression).snap(string 10 1) }) it(not, () { const tNot jsonSchemaToType({ not: { type: string, maxLength: 3 } }) attest(tNot.allows(123)).equals(true) attest(() tNot.assert(123)).throws( TraversalError: must be not: a string and at most length 3 (was 123) ) }) it(oneOf, () { const tOneOf jsonSchemaToType({ oneOf: [{ type: string, minLength: 10 }, { const: foo }] }) attest(tOneOf.allows(foo)).equals(true) attest(() tOneOf.assert(bar)).throws( TraversalError: must be valid according to jsonSchemaOneOfValidator (was bar) ) }) })这些断言同时揭示了实现细节allOf被折叠为 ArkType 的交集表达式not与oneOf则被实现为带名字的运行时 predicate类型 JSON 中会显示为$ark.jsonSchemaNotValidator、$ark.jsonSchemaOneOfValidator运行时的失败信息会精确描述必须恰好满足其中一个还是必须不满足某个子 Schema。总结迁移方向JSON Schema → ArkType使用ark/json-schema的jsonSchemaToType()支持string/number/integer/boolean/null/array/object及各组合关键字、const/enum能直接替换存量 JSON Schema 校验器导出方向ArkType → JSON Schema直接使用Type.toJsonSchema()无需额外包默认输出 draft-2020-12定义期类型安全用JsonSchema.*类型标注 Schema 对象即可获得编译期校验字符串 Schema 记得从ark/json-schema导入StringSchema迁移前自查确认没有使用dependencies、if/else/then且multipleOf均为整数。赞分享后端【免费下载链接】arktypeTypeScripts 1:1 validator, optimized from editor to runtime项目地址https://gitcode.com/gh_mirrors/ar/arktype点击查看免费下载相关推荐Trigger.dev schema-to-json 指南把 Zod、Yup、ArkType、Effect、TypeBox 统一转换为 JSON SchemaTrigger.dev schema to json 指南把 Zod、Yup、ArkType、Effect、TypeBox 统一转换为 JSON SchemaAI Agent后端任务调度开发工具可观测性AI 应用io-ts与JSON Schema如何将运行时类型转换为JSON Schema定义io ts与JSON Schema如何将运行时类型转换为JSON Schema定义 想要在TypeScript项目中实现运行时类型安全同时生成标准的JSON后端强大的 TypeScript 到 JSON Schema 转换器ts-json-schema-generator强大的 TypeScript 到 JSON Schema 转换器ts json schema generator 在软件开发中JSON Schema 是一种开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
