深入解析 Insomnia File Schemav5 文件格式的 JSON Schema 契约及其生成、校验与版本迁移机制【免费下载链接】insomniaThe open-source, cross-platform API client for GraphQL, REST, WebSockets, SSE and gRPC. With Cloud, Local and Git storage.项目地址: https://gitcode.com/GitHub_Trending/in/insomniaInsomnia 将所有对外交换的数据请求集合、API 设计文档、Mock 服务、全局环境、MCP 客户端统一为 v5 格式的.yaml文件而 schemas/insomnia.schema.5.1.json 就是这套文件格式的机器可读契约。本文基于 schemas/README.md 完整讲解该 JSON Schema 的覆盖范围、编辑器与 CI 中的校验用法、版本化策略与重新生成流程并结合仓库源码深入剖析其“从 Zod 生成”的管线以及schema_version双轨版本迁移机制读完你可以直接在项目或 CI 中为 Insomnia 文件接入自动校验并理解旧版本文件被自动升级到 5.1 的底层原理。它是什么一份描述 v5 文件格式的 JSON Schemainsomnia.schema.5.1.json是一份 JSON Schemadraft 2020-12描述Insomnia v5 文件格式——也就是你从 Insomnia 导出集合、设计文档、环境或 Mock 服务时得到的.yaml文件以及 Insomnia 在 Git 存储仓库中读写的那些文件。它的实际用途有三类编辑器/CI 校验在 VS Code 或 CI 流水线中校验和自动补全 Insomnia 文件AI Agent 的精确契约让 Agent 在生成或编辑 Insomnia 文件时有据可依、可校验Git 存储场景的一致性保障Git 仓库中的 Insomnia 文件与本地导入导出共用同一套结构定义。需要特别注意的一点是这份 schema 是从源码生成的。它的源头是 Insomnia 代码中作为唯一事实来源source of truth的 Zod schema——packages/insomnia/src/common/import-v5-parser.ts 中的InsomniaFileSchema这是导入/导出.yaml文件和 Git 存储时实际使用的同一套校验逻辑。因此 schema 文件不应手工编辑修改后必须通过重新生成流程更新。覆盖范围一个 type 字段区分五种文件顶层type字段是判别字段共五种文件类型type文件类型collection.insomnia.rest/5.0请求集合Request collectionspec.insomnia.rest/5.0API 规范 / 设计文档mock.insomnia.rest/5.0Mock 服务environment.insomnia.rest/5.0全局环境mcpClient.insomnia/5.0MCP 客户端从源码可以看到这五种类型正是 import-v5-parser.ts 中InsomniaFileSchema的z.discriminatedUnion(type, ...)五个分支CollectionSchema、ApiSpecSchema、MockServerSchema、GlobalEnvironmentsSchema、McpClientSchema。几个值得注意的实现细节type中的5.0与 schema 版本无关它是文件格式主类型跨版本保持稳定详见下一节的双轨版本策略。MCP 客户端故意不遵循insomnia.rest命名源码注释 写明mcpClient.insomnia/5.0的命名是为了防止旧版本 App 在同步此类文件时崩溃对应内部问题 INS-1762。五种类型共享相同的外壳都带schema_version默认5.1、name、meta再各带专属内容字段——集合/设计文档带collection、cookieJar、environments、certificatesMock 服务带server与routes全局环境只有environmentsMCP 客户端带mcpRequest。版本化策略不可变的版本文件 双轨版本号每个 schema 版本是一个独立的不可变文件每个 schema 版本都发布为独立文件insomnia.schema.version.json当前为 insomnia.schema.5.1.json。版本号升级时是在旧文件旁边新增一个文件而不是覆盖旧文件——这样每个历史版本都保持可寻址已发布的 schema URL 永远不会改变含义。当前版本由 schema-version.ts 中的常量定义export const INSOMNIA_SCHEMA_VERSION 5.1;使用方应当显式引用自己目标的具体版本——当 schema 升级时把 URL 中的版本号改掉即可前移旧项目继续引用旧版本文件也不会失效。数据文件的双轨版本type稳定schema_version演进生成脚本和 Zod schema 共同决定了一个关键的版本设计文件type字段永远保持*/5.0实际功能版本记录在schema_version字段中。这一策略在 migration.md 中有完整阐述向后兼容旧版本可以读新版本数据它们会忽略schema_version字段向前兼容新版本可以读旧版本数据自动执行迁移type字段跨版本保持稳定避免破坏导入导出与 Git 同步的识别逻辑schema_version表示功能可用版本缺失时默认按5.0原始版本处理。示例对比来自 migration.md# v5.0原始版本 type: collection.insomnia.rest/5.0 name: My Collection collection: - name: My Request headers: - name: Content-Type value: application/json id: header_123 # 该 id 字段在 v5.1 中被移除 # v5.1新特性type 保持不变 type: collection.insomnia.rest/5.0 # 为兼容性保持相同 schema_version: 5.1 # 新增用于标记功能版本 name: My Collection collection: - name: My Request headers: - name: Content-Type value: application/json # id 字段已在 v5.1 中移除对应的 Zod 侧定义见 CollectionSchematype是z.literal(collection.insomnia.rest/5.0)而schema_version是z.string().optional().default(INSOMNIA_SCHEMA_VERSION)——缺省即当前版本。v5.1 迁移做了什么当前唯一的迁移是 5.0 → 5.1实现位于 v5.1.ts 的cleanHeadersAndParameters()核心行为从headers、parameters、body.params、cookies、gRPCmetadata数组的元素中移除id字段从cookies中移除时间戳字段creation、lastAccessed过滤空条目无name/value的项但保留文件上传项type: file且有fileName和 OpenAPI$ref/schema/in/required条目移除非空校验后为空的数组以及只剩空字符串的scripts对象跳过spec.contents——其中是 OpenAPI 规范原文有自己独立的 schema不参与迁移对遗留的 headers 补齐缺失的name/value源码注释指出缺少这两个字段的旧数据会被误判为 gRPC 请求对应 INS-1822。这些行为有专门的回归测试 v5.1.test.ts。迁移在哪些入口生效迁移逻辑统一由 insomnia-schema-migrations/index.ts 提供其中migrateToLatestYaml()是主入口性能与容错策略很清晰提前退出数据已是最新版本时原样返回不做任何处理L70-L72按需应用只有版本号大于来源版本的迁移函数才会执行migrations注册表按版本排序L43-L49失败兜底迁移异常时回退返回原始内容不阻断主流程L91-L95属性顺序归一化可选传入 reference 内容normalizePropertyOrder()按参照对象重排键序与meta.id顺序避免 Git diff 检测因属性重排产生误报。从源码引用关系看migrateToLatestYaml至少在三处被调用数据导入insomnia-v5.ts、Git 克隆导入git-service.ts、以及Git 存储的 diff 计算git-vcs.ts 中对 HEAD 与 STAGE blob 应用迁移。新增迁移的步骤升版本号 → 新建v5.2.ts→ 注册进migrations数组 → 更新 Zod schema → 补测试在 migration.md 中有完整流程说明。生成管线从 Zod 到 JSON Schemaschema 由 packages/insomnia/scripts/generate-schema.ts 生成整条管线值得逐段看用 esbuild 打包解析器import-v5-parser.ts内部使用~/*tsconfig 路径别名单文件执行器无法解析脚本先用 esbuild配置alias: { ~: SRC_DIR }把它打包成临时 CJS 模块再加载同时把zod声明为 external 以共享同一实例bundleParser。z.toJSONSchema()的三个关键选项L112-L121io: input——按用户书写的数据校验字段默认值保持可选而不是输出形态unrepresentable: any——无法精确映射到 JSON Schema 的结构回退为宽松形态而非抛错cycles: ref——递归的 request-group / JSON 值 schema 通过$defs/$ref复用不做内联展开。normalizeSchema()归一化L60-L73删除所有default注解——它们不影响校验而某个 cookie 字段的默认值是crypto.randomUUID()不删掉会导致输出不确定、破坏 CI 的确定性比对从required数组中剔除expires等被z.preprocess(...)包装且内层带默认值的字段——Zod 计算可选性时“看不见”preprocess 包裹会把实际可选的字段误标为必填而解析器实际上接受其缺省。拼装元信息并落盘写入$schemadraft 2020-12、$id发布 URL、title与description输出到仓库根 schemas/ 目录下按版本命名的不可变文件文件名由INSOMNIA_SCHEMA_VERSION决定。脚本头部注释还特别说明生成的文件会提交进仓库并由 CI 漂移检查保持与源码同步。使用方式VS CodeYAML 扩展安装 YAML 扩展后在.vscode/settings.json中把 Insomnia 文件映射到 schema{ yaml.schemas: { https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json: [ **/*.insomnia.yaml, .insomnia/**/*.yml ] } }也可以在单个文件顶部用行内 modeline 指定# yaml-language-server: $schemahttps://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json type: collection.insomnia.rest/5.0 name: My Collection命令行 / CI用任意 JSON Schema 校验器都可以。以ajv-cli为例文件是 YAML需先转换例如用yqcurl -sO https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json yq -ojson . my-collection.insomnia.yaml my-collection.json ajv validate --specdraft2020 -s insomnia.schema.5.1.json -d my-collection.jsonNode.jsimport Ajv2020 from ajv/dist/2020.js; import addFormats from ajv-formats; import { readFileSync } from node:fs; import YAML from yaml; const schema JSON.parse(readFileSync(insomnia.schema.5.1.json, utf8)); const ajv addFormats(new Ajv2020({ allErrors: true, strict: false })); const validate ajv.compile(schema); const data YAML.parse(readFileSync(my-collection.insomnia.yaml, utf8)); if (!validate(data)) { console.error(validate.errors); process.exit(1); }注意strict: false生成的 schema 中存在无法精确映射的宽松结构见前文unrepresentable: any关闭 Ajv 的严格模式可避免加载告警addFormats则用于支持date-time等格式校验cookie 的expires等字段。给 AI Agent 的契约让 Agent 创建或编辑 Insomnia 文件时把 schema URL 作为必须遵循并用于自校验的契约Generate an Insomnia collection that conforms to the JSON Schema athttps://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json. The top-leveltypemust becollection.insomnia.rest/5.0.这条提示词的写法直接来自 schemas/README.md其可靠性正源于 schema 与 App 内部解析器同源通过 schema 校验的文件与 Insomnia 导入时的 Zod 校验是同一套约束。稳定 URL 与版本固定schema 以原始文件形式发布在默认分支上https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json这正是 schema 自身的$id值也就是上述各处应当引用的 URL与 generate-schema.ts 中的 SCHEMA_BASE_URL 一致。若需固定到某个具体应用版本把develop换成 release tag文档给出的示例为core12.0.0即可由于每个版本文件不可变develop分支上的文件名一旦写入就永远指向同一内容。重新生成与 CI 漂移检查修改 Zod schema 后运行npm run generate:schema -w insomnia该脚本定义在 packages/insomnia/package.json 中即esr --cache ./scripts/generate-schema.ts然后提交schemas/下更新后的文件。CI 会强制生成结果与源码保持一致.github/workflows/test.yml 中 “Check Insomnia JSON schema is up to date” 步骤会重新执行npm run generate:schema -w insomnia用git add -N schemas/将版本号升级产生的新文件标记为 intent-to-add再以git diff --exit-code schemas/判断是否漂移漂移则报错要求重新生成并提交::error::schemas/ is out of date. Run npm run generate:schema -w insomnia and commit the result.小结与延伸阅读Insomnia File Schema 的设计核心是“单一事实来源 不可变版本发布”Zod schemaimport-v5-parser.ts同时服务于运行时解析与公开 JSON Schema 的生成type稳定、schema_version演进的双轨版本策略让新旧数据互通迁移逻辑insomnia-schema-migrations/在导入、Git 克隆和 diff 三个入口统一生效CI 漂移检查则保证公开契约永不过期。关键文件清单schemas/README.md —— 本 schema 的使用说明本文主文档schemas/insomnia.schema.5.1.json —— 当前版本的 JSON Schemapackages/insomnia/scripts/generate-schema.ts —— 生成管线packages/insomnia/src/common/import-v5-parser.ts —— Zod 源头与类型定义packages/insomnia/src/common/insomnia-schema-migrations/migration.md —— 迁移指南与新增迁移流程packages/insomnia/src/common/insomnia-schema-migrations/v5.1.ts —— 5.1 迁移实现packages/insomnia/src/common/insomnia-schema-migrations/tests/v5.1.test.ts —— 迁移回归测试.github/workflows/test.yml —— CI 漂移检查【免费下载链接】insomniaThe open-source, cross-platform API client for GraphQL, REST, WebSockets, SSE and gRPC. With Cloud, Local and Git storage.项目地址: https://gitcode.com/GitHub_Trending/in/insomnia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考