深入解析 Insomnia File Schema：v5 文件格式的 JSON Schema 契约及其生成、校验与版本迁移机制

2026-09-05 23:05:59作者：袁立春Spencer

Insomnia 将所有对外交换的数据（请求集合、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 Schema

insomnia.schema.5.1.json 是一份 JSON Schema（draft 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 collection）
`spec.insomnia.rest/5.0`	API 规范 / 设计文档
`mock.insomnia.rest/5.0`	Mock 服务
`environment.insomnia.rest/5.0`	全局环境
`mcpClient.insomnia/5.0`	MCP 客户端

从源码可以看到这五种类型正是 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、certificates；Mock 服务带 server 与 routes；全局环境只有 environments；MCP 客户端带 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 侧定义见 CollectionSchema：type 是 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、gRPC metadata 数组的元素中移除 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 Schema

schema 由 packages/insomnia/scripts/generate-schema.ts 生成，整条管线值得逐段看：

用 esbuild 打包解析器：import-v5-parser.ts 内部使用 ~/* tsconfig 路径别名，单文件执行器无法解析，脚本先用 esbuild（配置 alias: { '~': SRC_DIR }）把它打包成临时 CJS 模块再加载，同时把 zod 声明为 external 以共享同一实例（bundleParser）。
z.toJSONSchema() 的三个关键选项（L112-L121）：
- io: '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 包裹，会把实际可选的字段误标为必填，而解析器实际上接受其缺省。
拼装元信息并落盘：写入 $schema（draft 2020-12）、$id（发布 URL）、title 与 description，输出到仓库根 schemas/ 目录下按版本命名的不可变文件，文件名由 INSOMNIA_SCHEMA_VERSION 决定。

脚本头部注释还特别说明：生成的文件会提交进仓库，并由 CI 漂移检查保持与源码同步。

使用方式

VS Code（YAML 扩展）

安装 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: $schema=https://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，需先转换，例如用 yq）：

curl -sO https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json
yq -o=json '.' my-collection.insomnia.yaml > my-collection.json
ajv validate --spec=draft2020 -s insomnia.schema.5.1.json -d my-collection.json

Node.js

import 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 at https://raw.githubusercontent.com/Kong/insomnia/develop/schemas/insomnia.schema.5.1.json. The top-level type must be collection.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（文档给出的示例为 core@12.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 schema（import-v5-parser.ts）同时服务于运行时解析与公开 JSON Schema 的生成；type 稳定、schema_version 演进的双轨版本策略让新旧数据互通，迁移逻辑（insomnia-schema-migrations/）在导入、Git 克隆和 diff 三个入口统一生效；CI 漂移检查则保证公开契约永不过期。关键文件清单：