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

本文介绍了在使用 JSON Schema 的 oneOf 关键字进行数据校验时，如何理解和处理可能出现的“Value is not defined in enum”错误。通过分析示例，解释了这种错误产生的原因，并强调了 JSON Schema 校验器正确报告错误的重要性。

在使用 JSON Schema 验证 JSON 数据时，oneOf 关键字允许数据满足多个子模式中的一个。然而，当数据不符合任何一个子模式时，校验器可能会报告多个错误，其中一种常见的错误是 "Value is not defined in enum"。 理解这种错误的含义以及如何处理它对于有效地使用 JSON Schema 至关重要。

理解 oneOf 和枚举校验

oneOf 关键字指定数据必须根据给定的多个 schema 中的一个进行验证。每个 schema 都可以包含各种验证规则，包括 enum 关键字，用于限制属性的值只能是预定义集合中的一个。

例如，以下 JSON Schema 使用 oneOf 来定义两种可能的结构，具体取决于 eventName 的值：

{
  "$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
            }
          }
        }
      }
    }
  ]
}

在此示例中，如果 eventName 是 "Test10" 或 "Test12"，则 totalAmount 必须大于 0。如果 eventName 是 "Test1"、"Test2" 或 "Test3"，则 totalAmount 必须小于 0。

错误消息的含义

当使用上述 schema 验证以下 JSON 数据时：

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

校验器会报告以下错误：

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." 指出 eventName 的值 "Test12" 不在第二个 oneOf 子模式的 enum 列表中。第二个错误 "Integer -5 is less than minimum value of 0." 指出 totalAmount 的值 -5 不满足第一个 oneOf 子模式中 exclusiveMinimum 的要求。

为什么会报告枚举错误？

重要的是要理解，校验器报告枚举错误是正确的行为。 oneOf 的目的是验证数据是否符合 至少一个 子模式。 如果数据不符合任何子模式，则校验失败，并且报告所有不符合的错误是有意义的。

Find JSON Path Online

Easily find JSON paths within JSON objects using our intuitive Json Path Finder

30

查看详情

在本例中，数据不符合第一个子模式，因为 totalAmount 小于 0。数据也不符合第二个子模式，因为 eventName 不是 "Test1"、"Test2" 或 "Test3"。 因此，校验器正确地报告了这两个错误。

如何处理枚举错误

虽然枚举错误是有效的，但在某些情况下，您可能希望以不同的方式处理它们。例如，您可能只想看到导致校验失败的 最相关的 错误。

不幸的是，JSON Schema 本身没有提供一种内置的方式来过滤或抑制特定的错误消息。 然而，您可以考虑以下方法：

1. 修改 Schema: 如果可能，重新设计 schema 以避免不必要的错误。例如，可以合并 oneOf 中的子模式，或者使用 if/then/else 结构来更精确地定义验证规则。

2. 后处理错误: 在代码中，您可以捕获校验器返回的错误列表，并根据您的需要进行过滤或排序。您可以根据 schema 路径或错误消息的内容来识别和删除不需要的错误。

3. 使用自定义校验器: 您可以编写自己的 JSON Schema 校验器，并自定义其行为以满足您的特定需求。这需要更多的工作，但提供了最大的灵活性。

总结

当使用 JSON Schema 的 oneOf 关键字时，"Value is not defined in enum" 错误通常是校验器正确报告数据不符合某个子模式的结果。 虽然不能直接抑制这些错误，但可以通过修改 schema、后处理错误或使用自定义校验器来管理它们。 理解这些错误的原因和处理方法可以帮助您更有效地使用 JSON Schema 进行数据验证。

以上就是使用 JSON Schema 校验 oneOf 时避免不必要的枚举错误的详细内容，更多请关注php中文网其它相关文章！