JSON Schema在MongoDB中是集合级强制数据契约，插入或更新时自动校验并拒绝不合规文档，具有服务端原子性、不可绕过性，仅对新写操作生效，不追溯旧数据。

什么是 jsonSchema 在 MongoDB 中的实际作用 它不是校验工具，而是集合级别的数据契约。MongoDB 会在插入或更新文档时自动按 schema 检查结构，不满足就直接拒绝写入，并返回 Document failed validation 错误。这和应用层手动校验有本质区别：schema 是服务端强制的、原子的、不可绕过的约束。

注意：只对 insertOne、insertMany、updateOne（含 upsert: true）等写操作生效；对已有旧文档不做 retroactive 校验，除非你显式触发重写（比如 replaceOne）。

如何给集合添加 jsonSchema 校验规则 必须通过 collMod 命令或创建集合时指定，不能事后用 createIndex 或其它方式“追加”。推荐在集合初建时一次性设好：

db.createCollection("users", {
  validator: {
    $jsonSchema: {
      bsonType: "object",
      required: ["name", "email"],
      properties: {
        name: { bsonType: "string", maxLength: 50 },
        email: { bsonType: "string", pattern: "^.+@.+$" },
        age: { bsonType: "int", minimum: 0, maximum: 150 }
      }
    }
  }
})

常见错误：

Expanso yaml-to-json

使用 Expanso Edge 管道将 YAML 输入转换为 JSON 格式。

下载

• 漏写外层 $jsonSchema 字段 —— 直接写 validator: { bsonType: "object" } 会静默失效
• 在已有集合上用 createCollection 覆盖 —— 实际不会修改，需用 runCommand({ collMod: ..., validator: ... })
• 把正则写成 JavaScript 字面量（/^.+@.+$/）—— 必须是字符串形式的 pattern

jsonSchema 中哪些字段类型和校验最常用也最容易踩坑 MongoDB 的 bsonType 和 JSON Schema 标准不完全一致，例如没有 number，只有 double、int、long、decimal 等具体类型。混用会导致意外放行或拦截：

• bsonType: "int" 只接受 32 位整数，42.0 或 NumberLong("42") 都会失败
• bsonType: "string" 不校验是否为空字符串，需额外加 minLength: 1
• required 只检查字段是否存在，不检查是否为 null；要禁止 null，得配合 enum: [{ $ne: null }] 或用 not: { type: "null" }
• 嵌套对象用 properties + required，但数组内元素校验要用 items，不是 property

更新 schema 时要注意什么 MongoDB 允许随时修改 validator，但新规则**立即生效**，且不区分“开发/生产”环境。一次宽松 → 严格变更可能批量阻断写入：

• 先用 db.runCommand({ collStats: "users" }) 查看当前文档数量，评估影响面
• 若要新增必填字段，可先设 required: [] + default（注意：MongoDB 不支持 default 关键字，得靠应用层或 $setOnInsert 补）
• 测试时用 updateOne({ _id: ObjectId("...") }, { $set: { newField: "test" } }) 触发校验，比 insert 更安全
• 线上变更建议搭配 validationLevel: "warn"（仅记录日志不报错），验证无误后再切到 "strict"

实际约束力取决于你是否启用 validationAction: "error"，默认就是 error；但如果集合早期没设 validator，后来加了，那些历史文档仍可读可查——只是再也改不了、删不了、也 insert 不进去任何不合规的新数据。这点常被忽略。