本文介绍如何使用 json schema 精确约束对象（如 employee）中多个可选字段——允许部分为 null，但禁止全部为 null，并提供可直接落地的 schema 写法、常见误区及完整示例。
本文介绍如何使用 json schema 精确约束对象（如 employee）中多个可选字段——允许部分为 null，但禁止全部为 null，并提供可直接落地的 schema 写法、常见误区及完整示例。
在构建 RESTful Java 后端 API（如 Spring Boot）时，常需对请求体（payload）进行强校验。例如 Employee 对象包含 empName、empAge、empAddress、empContact 四个字段，业务要求：每个字段均可为空（即允许 null），但整组字段不能全部为空——即至少有一个字段必须提供有效值（非 null 且符合其类型定义）。原 schema 中仅声明 "type": ["object", null] 存在语法错误，且缺乏“非全空”逻辑表达，需借助 JSON Schema 的组合关键字实现。
✅ 正确写法：使用 anyOf + 显式非空声明
核心思路是：枚举所有“至少一个字段存在且类型合法”的可能性。注意两点关键修正：
使用约定式提交（Conventional Commits）生成标准化的 Git 提交信息。适用于以下场景： (1) 暂存更改时需要提交信息； (2) 审查 diff 时希望获得结构化摘要； (3) 编写 PR 描述或变更日志（changelog）条目； (4) 用户明确要求“为本次更改编写提交信息”。 该功能会分析已暂存/未暂存的 diff，并生成按类型（type）划分范围的提交信息。
- null 必须加引号写作 "null"（JSON Schema 规范中，type 数组元素必须为字符串）；
- "type": ["object", "null"] 表示该字段可为 null 或任意 JSON 对象（⚠️注意：若本意是允许 string/number/null 等基础类型，请按实际需求调整，后文会说明）；
以下是修正后的完整 employee schema 片段：
"employee": {
"type": "object",
"default": {},
"properties": {
"empName": { "type": ["string", "null"] },
"empAge": { "type": ["integer", "null"] },
"empAddress": { "type": ["string", "null"] },
"empContact": { "type": ["string", "null"] }
},
"anyOf": [
{ "required": ["empName"], "properties": { "empName": { "type": "string" } } },
{ "required": ["empAge"], "properties": { "empAge": { "type": "integer" } } },
{ "required": ["empAddress"], "properties": { "empAddress": { "type": "string" } } },
{ "required": ["empContact"], "properties": { "empContact": { "type": "string" } } }
]
}? 为什么用 required + properties？
单纯写 "anyOf": [{ "properties": { "empName": { "type": "string" } } }, ...] 是不严谨的——它只声明“当 empName 存在时类型应为 string”，但未强制 empName 必须存在。因此必须配合 "required": ["empName"]，确保该分支成立的前提是该字段存在且非 null（因为 "type": "string" 已排除 null）。
⚠️ 常见误区与注意事项
- ❌ 错误写法："type": ["object", null] → null 未加引号，JSON 解析失败；
- ❌ 错误理解 "type": ["object", "null"] → 此处 "object" 表示值必须是 JSON 对象（如 {}），而非“任意类型”。若字段预期为字符串或数字，请改为 "string"/"integer"/"number" 等；
- ⚠️ 性能提示：anyOf 分支数随字段数线性增长（4 字段 → 4 分支），对超宽对象（如 >10 可选字段）建议在应用层补充校验，避免 schema 过于臃肿；
- ✅ 推荐实践：结合 additionalProperties: false 防止非法字段注入，增强安全性：
"employee": {
"type": "object",
"additionalProperties": false,
"properties": { /* ... */ },
"anyOf": [ /* ... */ ]
}✅ 总结
要实现“对象中多个字段可空、但不可全空”的语义约束，JSON Schema 并无原生关键字，必须通过 anyOf 枚举各字段的“存在且合法”情形，并在每个分支中使用 required + 精确 type 定义来排除 null。该方案完全兼容 JSON Schema Validation Draft 07/2020-12，可直接集成至 Spring Boot 的 @Valid + json-schema-validator、或前端表单校验库（如 AJV）中，保障前后端校验一致性。
