使用 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。

InsCode

InsCode 是CSDN旗下的一个无需安装的编程、协作和分享社区

下载

如何避免不必要的枚举错误

虽然错误信息可能看起来是“虚假”的，但它们实际上准确地反映了每个子 schema 的校验结果。 关键在于理解 oneOf 的工作方式：它会尝试用每个子 schema 校验 JSON 数据，并报告所有失败的子 schema 的错误。

要避免这种“虚假”错误，需要更仔细地设计 oneOf 中的子 schema，确保它们之间的互斥性更强。 换句话说，尽量让每个子 schema 针对不同的数据结构或类型进行校验，避免出现重叠或模糊的情况。

在这个例子中，错误是无法完全避免的，因为 oneOf 的设计目的就是校验数据是否满足一个且仅一个子schema。 校验器会报告每个不满足的子schema的原因。

总结：

1. 理解 oneOf 的行为: oneOf 会尝试匹配所有子 schema，并报告所有不匹配的错误。
2. 清晰定义子 schema: 确保 oneOf 中的每个子 schema 具有明确且互斥的校验目标。
3. 仔细分析错误信息: 不要轻易忽略错误信息，仔细分析每个错误的原因，判断是否需要调整 schema 或数据。

通过理解 oneOf 的工作原理，并采取相应的策略，可以有效地利用 JSON Schema 进行数据校验，提高数据质量和应用程序的可靠性。