使用 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 的目的是验证数据是否符合 至少一个 子模式。 如果数据不符合任何子模式，则校验失败，并且报告所有不符合的错误是有意义的。

讯飞智作-讯飞配音

讯飞智作是一款集AI配音、虚拟人视频生成、PPT生成视频、虚拟人定制等多功能的AI音视频生产平台。已广泛应用于媒体、教育、短视频等领域。

67

查看详情

在本例中，数据不符合第一个子模式，因为 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中文网其它相关文章！