精通 JSON Schema 条件验证：根据枚举值动态设置必填字段-java教程-PHP中文网

精通 JSON Schema 条件验证：根据枚举值动态设置必填字段

心靈之曲

发布： 2025-11-27 20:51:01

原创

473人浏览过

精通 JSON Schema 条件验证：根据枚举值动态设置必填字段

本文深入探讨了如何利用 json schema 的 if/then 结构实现复杂的条件验证，特别是当一个顶级字段的必填性依赖于另一个嵌套字段的特定枚举值时。通过一个实际的订单数据验证案例，文章详细讲解了如何构建精准的条件逻辑，确保数据模型在不同业务场景下的灵活性和准确性，避免常见的验证错误。

在数据交换和存储中，JSON Schema 是定义和验证数据结构的标准工具。然而，业务逻辑往往并非一成不变，某些字段的必填性可能需要根据其他字段的值动态调整。这种“条件必填”的需求，正是 JSON Schema 中 if/then/else 关键字所擅长解决的问题。

核心挑战：根据嵌套字段值动态要求字段

设想一个订单管理系统，其中包含不同类型的操作（例如“ORDER”、“TRANSFER”、“WITHDRAWAL”等）。对于类型为“ORDER”的订单，我们要求必须提供商品列表（items 字段）；而对于其他类型的订单，items 字段则不是必需的。

最初的尝试可能是在 attributes 内部的 allOf 块中，针对 order_type 为 "ORDER" 的情况，尝试添加 required: ["items"]。然而，这种做法通常会导致验证失败，因为 items 是顶层属性，而不是 attributes 内部的属性。if/then 关键字的应用范围是其所在模式的实例，因此在 attributes 内部声明 required: ["items"] 意味着要求 attributes 对象本身包含 items 属性，这显然与我们的设计不符。

JSON Schema 条件验证机制 (if/then)

JSON Schema Draft 07 引入的 if、then 和 else 关键字提供了强大的条件逻辑能力：

if: 定义一个子模式作为条件。如果数据实例符合 if 中定义的模式，则应用 then 中定义的模式。
then: 当 if 条件满足时应用的子模式。
else: 当 if 条件不满足时应用的子模式（可选）。

理解 if 关键字的关键在于，它所描述的条件是针对当前正在被验证的整个数据实例而言的。这意味着，即使条件是基于嵌套属性的值，if 块本身也需要描述如何定位到这个嵌套属性。

正确实现方案

为了解决上述问题，我们需要将条件验证逻辑放在顶层，并精确地描述 attributes.order_type 的路径和值。以下是经过优化的 JSON Schema 示例：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Validaciones sobre el esquema Order",
  "type": "object",
  "properties": {
    "warehouse_id": {
      "type": "string"
    },
    "operation_type": {
      "type": "string"
    },
    "order_id": {
      "type": "number"
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          }
        },
        "required": [
          "sku",
          "quantity"
        ],
        "additionalProperties": false
      }
    },
    "attributes": {
      "type": "object",
      "properties": {
        "order_type": {
          "type": "string",
          "enum": [
            "ORDER",
            "TRANSFER",
            "WITHDRAWAL",
            "DISPOSAL",
            "FRESH"
          ]
        },
        "etd": {
          "type": "string",
          "pattern": "^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])(?:T)(0[0-9]|1[0-9]|2[0-3]):(0[0-9]|1[0-9]|2[0-9]|3[0-9]|4[0-9]|5[0-9]):(0[0-9]|1[0-9]|2[0-9]|3[0-9]|4[0-9]|5[0-9])(?:Z)$"
        },
        "volume": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "typology": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "CONVEYABLE",
            "NON_CONVEYABLE"
          ]
        }
      },
      "required": [
        "order_type"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "warehouse_id",
    "operation_type",
    "attributes"
  ],
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "attributes": {
            "properties": {
              "order_type": {
                "const": "ORDER"
              }
            },
            "required": [
              "order_type"
            ]
          }
        },
        "required": [
          "attributes"
        ]
      },
      "then": {
        "required": [
          "items"
        ]
      }
    }
  ]
}

登录后复制

关键解析

allOf 的位置: 条件逻辑被放置在最顶层的 allOf 数组中。allOf 确保所有子模式都必须通过验证。
if 子句:
- if 内部的结构描述了如何定位到 order_type 属性。它不是简单地写 order_type，而是从根层级开始，通过 properties 逐步深入到 attributes 对象，再到 order_type 属性。
- "properties": { "attributes": { ... } }：这表示我们关注的是顶层 properties 中的 attributes 属性。
- "attributes": { "properties": { "order_type": { "const": "ORDER" } }, "required": ["order_type"] }：这进一步描述了 attributes 属性本身是一个对象，它包含一个 order_type 属性，且该属性的值必须是 "ORDER"。同时，为了确保 order_type 确实存在，我们也在 attributes 内部声明 required: ["order_type"]。
- "required": ["attributes"]：确保顶层数据中必须包含 attributes 属性，这是访问 order_type 的前提。
then 子句:
- "then": { "required": ["items"] }：当 if 条件（即 attributes.order_type 为 "ORDER"）满足时，items 属性在顶层被声明为必填。

通过这种方式，我们精确地表达了“如果数据实例中存在 attributes 且 attributes.order_type 的值为 "ORDER"，那么 items 属性必须存在”的逻辑。

验证实例

让我们通过几个示例来验证这个 Schema 的行为：

Remusic

Remusic - 免费的AI音乐、歌曲生成工具

514

查看详情

1. 无效数据示例：order_type 为 "ORDER" 但缺少 items

{
    "warehouse_id": "ARTW01",
    "operation_type": "outbound",
    "order_id": 41789301078,
    "attributes": {
        "volume": 1350,
        "etd": "2022-11-11T18:25:00Z",
        "order_type": "ORDER"
    }
}

登录后复制

验证结果： 失败。因为 order_type 是 "ORDER"，根据 then 规则，items 字段是必需的，但此数据中缺少。

2. 有效数据示例：order_type 为 "ORDER" 且包含 items

{
    "warehouse_id": "ARTW01",
    "operation_type": "outbound",
    "order_id": 41789301078,
    "items": [
        {
            "sku": "SKU001",
            "quantity": 5
        }
    ],
    "attributes": {
        "volume": 1350,
        "etd": "2022-11-11T18:25:00Z",
        "order_type": "ORDER"
    }
}

登录后复制

验证结果： 成功。条件满足，且 items 字段存在并符合其自身的模式定义。

3. 有效数据示例：order_type 不为 "ORDER" 且缺少 items

{
    "warehouse_id": "ARTW01",
    "operation_type": "inbound",
    "order_id": 41789301079,
    "attributes": {
        "volume": 200,
        "etd": "2022-11-12T10:00:00Z",
        "order_type": "TRANSFER"
    }
}

登录后复制

验证结果： 成功。if 条件不满足，因此 then 规则不被应用，items 字段不是必需的。

注意事项与最佳实践

理解 if 的作用域: if 关键字的条件是针对其所在的 JSON Schema 节点所验证的整个数据实例。因此，当条件涉及嵌套属性时，需要在 if 内部完整地描述该属性的路径。
required 关键字的放置: required 关键字声明的是当前模式级别下的必填属性。在上述示例中，items 是顶层属性，所以其必填性声明在顶层 then 块中。
allOf 的灵活性: allOf 可以用于组合多个条件逻辑或多个子模式，使其共同作用于数据实例。
保持模式简洁: 在开发和调试时，可以像答案中那样，暂时移除不相关的 Schema 部分，只关注条件验证的核心逻辑，以提高可读性和定位问题。
充分测试: 对于复杂的条件验证，务必准备多组测试数据，覆盖所有条件分支（条件满足、条件不满足、边界情况），确保 Schema 行为符合预期。