使用 JSON Schema 的 oneOf 校验时避免不必要的枚举错误-java教程-PHP中文网

使用 JSON Schema 的 oneOf 校验时避免不必要的枚举错误

心靈之曲

发布： 2025-09-09 19:37:01

原创

696人浏览过

使用 json schema 的 oneof 校验时避免不必要的枚举错误

本文旨在帮助开发者理解和解决在使用 JSON Schema 的 oneOf 关键字进行校验时，可能出现的“值未在枚举中定义”的错误。通过分析错误产生的原因，提供避免此类错误的策略，并强调正确理解 oneOf 行为的重要性，从而提升 JSON Schema 校验的准确性和效率。

理解 oneOf 的行为

oneOf 关键字用于指定 JSON 数据必须匹配多个子 schema 中的一个且仅一个。当 JSON 数据未能满足其中任何一个子 schema 时，校验器会报告所有子 schema 的错误信息，这可能导致一些看似“虚假”的错误出现。

例如，考虑以下 JSON Schema：

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "type": "object",
  "properties": {
    "eventName": {
      "type": "string",
      "enum": ["Test10", "Test12", "Test1", "Test2", "Test3"]
    },
    "eventPayload": {
      "type": "object",
      "properties": {
        "totalAmount": {
          "type": "number"
        }
      }
    }
  },
  "oneOf": [
    {
      "properties": {
        "eventName": {
          "enum": ["Test10", "Test12"]
        },
        "eventPayload": {
          "properties": {
            "totalAmount": {
              "exclusiveMinimum": 0
            }
          }
        }
      }
    },
    {
      "properties": {
        "eventName": {
          "enum": ["Test1", "Test2", "Test3"]
        },
        "eventPayload": {
          "properties": {
            "totalAmount": {
              "exclusiveMaximum": 0
            }
          }
        }
      }
    }
  ]
}

登录后复制

以及以下 JSON 数据：

{
  "eventName": "Test12",
  "eventPayload": {
    "totalAmount": -5
  }
}

登录后复制

使用上述 schema 校验 JSON 数据时，会得到如下错误：

Message: Value "Test12" is not defined in enum.
Schema path: #/oneOf/1/properties/eventName/enum
Message: Integer -5 is less than minimum value of 0.
Schema path: #/oneOf/0/properties/eventPayload/properties/totalAmount/minimum

登录后复制

第一个错误 "Value "Test12" is not defined in enum." 是由于第二个子 schema 中 eventName 的 enum 仅包含 "Test1", "Test2", "Test3"，而 JSON 数据中的 eventName 为 "Test12"。第二个错误 "Integer -5 is less than minimum value of 0." 是由于第一个子 schema 中 totalAmount 的 exclusiveMinimum 设置为 0，而 JSON 数据中的 totalAmount 为 -5。