MongoDB Atlas用TypeBox的$jsonSchema报未知examples关键字错误

1. 传入MongoDB前清洗Schema移除不兼容字段 #

之前尝试的Type.Strict()仅会处理TypeBox内部生成的自定义元字段，不会移除手动传入的examples属性；配置ajv自定义keywords仅作用于Fastify侧的运行时校验，完全不会修改传给MongoDB的Schema对象，两个方案无效属于预期情况。
最可控的实现方式是写一个深度递归的清洗函数，遍历Schema所有节点，移除MongoDB不支持的关键字：

/**
 * 递归清洗Schema，移除MongoDB不识别的关键字
 * @param {any} schema 待处理的TypeBox Schema
 * @returns 适配MongoDB $jsonSchema 规则的Schema
 */
function cleanSchemaForMongo(schema) {
  if (typeof schema !== 'object' || schema === null) return schema
  if (Array.isArray(schema)) return schema.map(item => cleanSchemaForMongo(item))

  const cleaned = {}
  for (const key of Object.keys(schema)) {
    // 黑名单：所有MongoDB不支持的关键字都可以加到这个数组里
    if (['examples'].includes(key)) continue
    cleaned[key] = cleanSchemaForMongo(schema[key])
  }
  return cleaned
}

// 调用示例
await database.command({
  collMod: 'users',
  validator: {
    $jsonSchema: cleanSchemaForMongo(UserSchema),
  },
})

这个递归逻辑会自动覆盖所有嵌套场景，包括嵌套对象的properties、数组的items、组合校验规则allOf/anyOf/oneOf里的子Schema，不需要额外写特殊分支。后续如果遇到其他MongoDB不识别的关键字（比如部分低版本不支持的$comment、$schema、default），直接加到黑名单数组即可。

2. MongoDB Atlas侧可行性说明 #

目前Atlas全系列实例没有可配置的修复方案：

• 免费/共享级实例（M0/M2/M5）完全封锁setParameter命令权限，没有任何入口可以调整jsonSchema的未知关键字忽略规则
• 付费专属实例（M10及以上）的可修改参数白名单中，也没有开放jsonSchema相关的容错配置项，即便是提交工单也无法开启该权限
  不需要在Atlas侧的配置上浪费排查时间。

3. 其他可落地的优化思路 #

• 从Schema定义层做拆分：把所有字段的核心校验规则（type、pattern、maxLength、required、additionalProperties等MongoDB兼容的规则）抽成基础Schema，给Fastify用的接口校验Schema在基础Schema上通过Type.Intersect或者对象扩展追加examples、description这类文档属性，MongoDB侧直接用基础Schema组装集合校验规则，从根源上避免不兼容字段流入。示例：

  // 核心校验规则，仅保留MongoDB兼容字段
  const HandleBaseSchema = Type.RegEx(/^[a-zA-Z0-9_-]{1,24}$/, {
    title: 'Handle',
    maxLength: 24
  })
  // Fastify侧使用的版本，追加接口文档需要的examples字段
  export const HandleSchema = Type.Intersect([HandleBaseSchema], {
    examples: ['harry-potter', 'jane-doe-99']
  })
  // MongoDB侧使用基础Schema组装集合规则
  const UserBaseSchema = Type.Object({
    _id: HandleBaseSchema
    // 其余字段同理
  }, { additionalProperties: false })
  

• 清洗逻辑可以换成白名单模式：如果后续遇到的不兼容关键字较多，可以反过来只保留MongoDB官方文档明确列出支持的jsonSchema关键字，其余字段一律过滤，比黑名单模式稳定性更高，不用每次遇到新的不兼容字段再改代码。
• 不要尝试通过调低MongoDB校验等级绕过：比如把validationAction设为warn这类操作，仅在Schema本身解析成功后才会生效，Schema包含未知关键字时，创建/修改集合校验规则的命令会直接报错，根本不会走到写入校验逻辑。

内容的提问来源于stack exchange，提问作者Wickramaranga