使用 JSON Schema 中的 oneOf 避免不必要的枚举错误

本文旨在帮助开发者理解和解决在使用 JSON Schema 的 oneOf 关键字进行验证时，可能出现的看似“虚假”的枚举错误。我们将通过一个实际案例，分析错误产生的原因，并提供相应的解决方案，以确保 json 数据的有效性和准确性。

理解 oneOf 的工作原理

oneOf 关键字用于指定 JSON 数据必须匹配多个子模式中的 一个。 验证器会尝试匹配所有子模式，并报告每个不匹配的原因。 这就导致了即使数据最终匹配了其中一个子模式，但仍然会显示其他子模式的验证失败信息。

案例分析

考虑以下 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   } }

验证器会报告以下错误：

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

错误分析：

第一个错误看似“虚假”，因为 Test12 确实在顶层 eventName 的枚举中，并且也满足了 oneOf 的第一个子模式中 eventName 的枚举。 然而，验证器仍然报告了第二个子模式中 eventName 的枚举验证失败。

Fotor AI Image Upscaler

Fotor推出的AI图片放大工具

48

查看详情

解决方案和注意事项

虽然无法完全避免这种“虚假”错误，但可以采取以下策略来减少混淆，并更好地理解验证结果：

1. 理解错误报告的含义： 清楚地认识到 oneOf 会尝试匹配 所有 子模式，并报告每个子模式的失败原因。 这意味着即使最终匹配了一个子模式，其他子模式的错误仍然会显示。

2. 优化 Schema 设计： 仔细考虑 schema 的设计。 在某些情况下，可以重新组织 schema，避免使用 oneOf，或者将一些通用约束放在顶层，减少子模式之间的差异。 然而，这并不总是可行，因为 oneOf 通常用于处理具有不同结构和约束的 JSON 数据。

3. 自定义验证逻辑 (如果适用): 在某些情况下，如果 JSON Schema 的验证能力不足以满足需求，可以考虑使用编程语言编写自定义的验证逻辑。 这样可以更精确地控制验证过程，并生成更清晰的错误报告。 例如，可以使用 JavaScript 或 python 编写代码来检查 eventName 的值，并根据不同的值执行不同的验证步骤。

4. 忽略“虚假”错误 (谨慎使用): 在理解错误报告的含义后，可以有选择性地忽略某些错误。 例如，如果确定 eventName 的值确实匹配了 oneOf 的一个子模式，并且其他错误与该子模式无关，则可以忽略这些错误。 但是，必须非常谨慎地使用这种方法，确保不会忽略真正的错误。

总结

在使用 JSON Schema 的 oneOf 关键字时，可能会遇到看似“虚假”的枚举错误。 这是因为验证器会尝试匹配所有子模式，并报告每个子模式的失败原因。 理解 oneOf 的工作原理，优化 Schema 设计，以及在必要时使用自定义验证逻辑，可以帮助开发者更好地处理这些错误，并确保 JSON 数据的有效性和准确性。 记住，最重要的是理解错误报告的含义，并根据具体情况做出正确的判断。