本文介绍如何在 JSON Schema 中精准表达“对象内多个可选字段不能全部为 null，至少需有一个非空值”的业务约束，通过 anyOf 组合校验与类型修正实现可靠验证。
本文介绍如何在 json schema 中精准表达“对象内多个可选字段不能全部为 null，至少需有一个非空值”的业务约束，通过 `anyof` 组合校验与类型修正实现可靠验证。
在构建 RESTful API（如 Java Spring Boot 后端）时，常需对请求体（payload）中的嵌套对象进行精细化校验。典型场景是：Employee 对象包含若干可选字段（如 empName、empAge、empAddress、empContact），允许单个字段为 null，但禁止全部字段同时为 null——即必须至少存在一个有效（非 null）值。原 Schema 仅声明了各字段支持 "object" 或 null 类型，却未施加“非全空”逻辑约束，因此无法满足该业务规则。
✅ 正确的 JSON Schema 实现
首先需修正基础语法错误：JSON Schema 中 null 类型必须写作 "null"（字符串），而非 null（JSON 值）。其次，核心逻辑需借助 anyOf —— 它表示“满足其中任意一项即通过校验”，恰好契合“至少一个字段非空”的语义。
以下是完整、可直接使用的 employee 子 Schema：
"employee": {
"type": "object",
"default": {},
"properties": {
"empName": { "type": ["object", "null"] },
"empAge": { "type": ["object", "null"] },
"empAddress": { "type": ["object", "null"] },
"empContact": { "type": ["object", "null"] }
},
"anyOf": [
{ "required": ["empName"], "properties": { "empName": { "not": { "type": "null" } } } },
{ "required": ["empAge"], "properties": { "empAge": { "not": { "type": "null" } } } },
{ "required": ["empAddress"], "properties": { "empAddress": { "not": { "type": "null" } } } },
{ "required": ["empContact"], "properties": { "empContact": { "not": { "type": "null" } } } }
]
}? 说明：
- 每个 anyOf 分支使用 required + not { "type": "null" } 组合，确保对应字段存在且不为 null；
- 仅需任一分支成立（即任一字段非空），整个 anyOf 即校验通过；
- 若所有字段均为 null 或缺失，则所有分支均失败，整体校验拒绝该对象。
⚠️ 注意事项与最佳实践
- 避免误用 properties 直接嵌套字段校验：原始答案中 {"properties": {"empName": ...}} 写法不合法（properties 必须位于 object 类型定义下），正确方式应如上所示，结合 required 与 not；
- null 类型兼容性：确保所用 JSON Schema 验证器支持 nullable 语义（如 Draft-07 及以上版本），并启用 strictTypes 或等效配置；
- 可扩展性优化：若字段数量增加，建议配合工具生成 anyOf 列表，或考虑在应用层（如 Java Bean Validation）补充 @AssertTrue 自定义校验，保持 Schema 简洁；
-
测试用例建议：务必覆盖以下边界情况：
- ✅ { "empName": { "value": "Alice" } } → 通过
- ❌ { "empName": null, "empAge": null, "empAddress": null, "empContact": null } → 拒绝
- ❌ {}（空对象）→ 拒绝（因无任何字段非空）
✅ 总结
JSON Schema 本身不提供“非全空”原语，但可通过 anyOf + required + not { "type": "null" } 的组合模式严谨表达该约束。关键在于理解 anyOf 的逻辑或特性，并严格遵循 Schema 语法规范（如 "null" 字符串写法）。该方案零侵入、纯声明式，适用于各类支持 Draft-07+ 的验证器（如 json-schema-validator、ajv、Spring Cloud Contract），是微服务接口契约治理中的实用范式。
