本文介绍如何在 JSON Schema 中精确表达“对象内多个可选字段不得全部为 null”的业务约束，通过 anyOf 组合校验与类型修正，实现对 Employee 等复合对象的健壮性验证。
本文介绍如何在 json schema 中精确表达“对象内多个可选字段不得全部为 null”的业务约束，通过 `anyof` 组合校验与类型修正，实现对 employee 等复合对象的健壮性验证。
在构建 RESTful API（尤其是 Java Spring Boot 等后端服务）时，常需对请求体（payload）中的嵌套对象进行精细化校验。典型场景如 Employee 对象包含 empName、empAge、empAddress、empContact 四个字段——它们均允许为 null 或缺失，但禁止全部为空（即对象不能是逻辑上的“空壳”）。原 Schema 仅声明各字段可为 "object" 或 "null"，却未约束“至少一个字段必须非空”，导致无效数据（如 { "employee": {} } 或 { "employee": { "empName": null, "empAge": null, ... } }）仍能通过校验。
要达成该语义，需两步关键修正：
✅ 第一步：修正类型声明语法
JSON Schema 中 null 是独立基础类型，必须用字符串 "null" 表示，不可写作 null 字面量；同时，"type": ["object", "null"] 表示该字段可为对象或显式 null（注意：不包含 undefined 或缺失字段）。正确写法如下：
"empName": {
"type": ["object", "null"]
},
"empAge": {
"type": ["object", "null"]
},
"empAddress": {
"type": ["object", "null"]
},
"empContact": {
"type": ["object", "null"]
}⚠️ 注意：若字段还允许字符串、数字等其他类型，需一并加入数组，例如 "type": ["string", "null"]；此处假设业务中这些字段本身应为对象（如 empAddress 是地址对象），故保留 "object"。
✅ 第二步：强制“至少一个字段非空”
JSON Schema 原生不支持“非全空”聚合条件，但可通过 anyOf 构建互斥有效分支：只要任一字段存在且类型合法（即非 null），即满足整体约束。将 anyOf 应用于 employee 对象层级，每个分支声明一个字段必须为 "object"（即非 null 且为对象）：
"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": { "type": "object" } } },
{ "required": ["empAge"], "properties": { "empAge": { "type": "object" } } },
{ "required": ["empAddress"], "properties": { "empAddress": { "type": "object" } } },
{ "required": ["empContact"], "properties": { "empContact": { "type": "object" } } }
]
}? 为什么加 required？
单纯 "properties": { "empName": { "type": "object" } } 仅校验当 empName 存在时其类型，但无法阻止字段缺失。"required": ["empName"] 强制该字段必须存在且非 null，结合 "type": "object" 确保其为有效对象。四个分支覆盖所有“至少一个字段有效”的情形。
? 补充说明与最佳实践
- 兼容缺失字段：上述 anyOf 方案天然兼容字段缺失（如请求中未传 empAge），因每个分支只约束自身字段，其余字段仍按 properties 定义允许 null 或缺失。
- 避免常见错误：勿使用 not + allOf 否定全空（逻辑复杂且易出错）；勿遗漏 required 导致分支失效；切勿将 "null" 写作 null。
- Java 集成提示：若使用 json-schema-validator（如 everit-org）或 Spring Cloud Contract，确保库版本支持完整 JSON Schema Draft-07 语义；对于更复杂约束，可考虑在 Controller 层添加 @Valid 自定义校验器作为补充。
通过以上结构化 Schema 设计，即可精准表达“Employee 对象允许多字段为 null，但禁止全空”的业务规则，在保障灵活性的同时守住数据有效性底线。
