本文介绍了在使用 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 的目的是验证数据是否符合 至少一个 子模式。 如果数据不符合任何子模式，则校验失败，并且报告所有不符合的错误是有意义的。
在本例中，数据不符合第一个子模式，因为 totalAmount 小于 0。数据也不符合第二个子模式，因为 eventName 不是 "Test1"、"Test2" 或 "Test3"。 因此，校验器正确地报告了这两个错误。
如何处理枚举错误
虽然枚举错误是有效的，但在某些情况下，您可能希望以不同的方式处理它们。例如，您可能只想看到导致校验失败的 最相关的 错误。
不幸的是，JSON Schema 本身没有提供一种内置的方式来过滤或抑制特定的错误消息。 然而，您可以考虑以下方法：
修改 Schema: 如果可能，重新设计 schema 以避免不必要的错误。例如，可以合并 oneOf 中的子模式，或者使用 if/then/else 结构来更精确地定义验证规则。
后处理错误: 在代码中，您可以捕获校验器返回的错误列表，并根据您的需要进行过滤或排序。您可以根据 schema 路径或错误消息的内容来识别和删除不需要的错误。
使用自定义校验器: 您可以编写自己的 JSON Schema 校验器，并自定义其行为以满足您的特定需求。这需要更多的工作，但提供了最大的灵活性。
总结
当使用 JSON Schema 的 oneOf 关键字时，"Value is not defined in enum" 错误通常是校验器正确报告数据不符合某个子模式的结果。 虽然不能直接抑制这些错误，但可以通过修改 schema、后处理错误或使用自定义校验器来管理它们。 理解这些错误的原因和处理方法可以帮助您更有效地使用 JSON Schema 进行数据验证。
