本文深入探讨了如何在 json schema 中实现复杂的条件验证逻辑，特别是当一个顶级属性的必填性依赖于另一个嵌套对象中的字段值时。我们将通过一个订单数据模型示例，演示如何利用 `if`/`then` 关键字精确控制 `items` 属性，使其仅在 `order_type` 为 'order' 时才被强制要求，从而确保数据模型的灵活性与准确性。
JSON Schema 作为一种强大的数据结构描述语言，广泛应用于API接口定义、数据校验等场景。在实际应用中，我们经常会遇到需要根据数据中某个字段的值，来动态决定其他字段的必填性或结构的情况。例如，在一个订单（Order）数据模型中，只有当 attributes 对象中的 order_type 字段为 "ORDER" 时，顶层的 items 数组才必须存在；对于其他 order_type 类型（如 "TRANSFER"、"WITHDRAWAL" 等），items 字段则可以是可选的甚至不存在。
这种条件性必填的需求，如果处理不当，可能导致 Schema 过度复杂或验证不准确。本文将详细介绍如何利用 JSON Schema 的 if/then 关键字来优雅地解决此类问题。
JSON Schema Draft 07 引入了 if、then 和 else 关键字，它们共同提供了强大的条件逻辑能力。
理解 if、then 的作用域至关重要。if 关键字所描述的条件是针对其所在层级的实例数据进行评估的。同样，then 关键字所定义的验证规则也会应用于 if/then 所在的层级。
在尝试解决“order_type 为 'ORDER' 时 items 必填”的问题时，开发者常犯以下错误：
在 attributes 内部定义条件： 尝试在 attributes 属性的定义内部使用 allOf 和 if/then 来控制 items。
"attributes": {
// ... 其他属性定义 ...
"allOf": [
{
"if": {
"properties": { "order_type": { "const": "ORDER" } }
},
"then": {
// 这里尝试要求 items，但这是错误的
// 因为这个 allOf 的作用域是 attributes 对象本身，
// 无法触及顶层的 items 属性。
"required": ["items"] // 错误！items 不在 attributes 内部
}
}
]
}误区解释： attributes 内部的条件逻辑只能影响 attributes 对象自身的属性。items 是与 attributes 同级的顶层属性，因此无法在此处进行控制。
在根级别 allOf 中直接引用嵌套属性： 尝试在根级别的 allOf 中直接使用 order_type 作为 if 条件。
"allOf": [
{
"if": {
"properties": {
"order_type": { "const": "ORDER" } // 错误！order_type 不是根级别的属性
}
},
"then": { "required": ["items"] }
}
]误区解释： if 关键字所描述的条件是针对其所在层级的实例数据进行评估的。在根级别，order_type 并不是一个直接的属性，它嵌套在 attributes 内部。因此，if 必须完整地描述到达 order_type 的路径。
解决此问题的关键在于将 if/then 结构放置在 Schema 的根级别，并在 if 条件中完整描述 attributes.order_type 的路径和值。
以下是结合了原始问题中的完整 Schema 结构，并进行了修正的示例：
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://json-schema.org/draft-07/schema#",
"title": "Validaciones sobre el esquema Order",
"type": "object",
"properties": {
"warehouse_id": {
"type": "string"
},
"operation_type": {
"type": "string"
},
"order_id": {
"type": "number"
},
"items": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"sku": {
"type": "string",
"minLength": 1,
"maxLength": 50
},
"quantity": {
"type": "integer",
"minimum": 1
}
},
"required": [
"sku",
"quantity"
],
"additionalProperties": false
}
},
"attributes": {
"type": "object",
"properties": {
"order_type": {
"type": "string",
"enum": [
"ORDER",
"TRANSFER",
"WITHDRAWAL",
"DISPOSAL",
"FRESH"
]
},
"etd": {
"type": "string",
"pattern": "^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])(?:T)(0[0-9]|1[0-9]|2[0-3]):(0[0-9]|1[0-9]|2[0-9]|3[0-9]|4[0-9]|5[0-9]):(0[0-9]|1[0-9]|2[0-9]|3[0-9]|4[0-9]|5[0-9])(?:Z)$"
},
"volume": {
"type": ["integer", "null"],
"minimum": 0
},
"typology": true
},
"required": [
"order_type"
],
"allOf": [
{
"if": {
"properties": {
"order_type": {
"const": "ORDER"
}
},
"required": [
"order_type"
]
},
"then": {
"properties": {
"order_type": true,
"etd": true,
"volume": true,
"typology": {
"type": ["string", "null"],
"enum": [
"CONVEYABLE",
"NON_CONVEYABLE"
]
}
},
"required": [
"order_type",
"etd"
],
"additionalProperties": false
}
},
{
"if": {
"properties": {
"order_type": {
"const": "TRANSFER"
}
},
"required": [
"order_type"
]
},
"then": {
"properties": {
"order_type": true,
"etd": true,
"volume": true
},
"required": [
"order_type",
"etd"
],
"additionalProperties": false
}
},
{
"if": {
"properties": {
"order_type": {
"const": "WITHDRAWAL"
}
},
"required": [
"order_type"
]
},
"then": {
"properties": {
"order_type": true,
"etd": true,
"volume": true
},
"required": [
"order_type",
"etd"
],
"additionalProperties": false
}
},
{
"if": {
"properties": {
"order_type": {
"const": "DISPOSAL"
}
},
"required": [
"order_type"
]
},
"then": {
"properties": {
"order_type": true,
"etd": true,
"volume": true
},
"required": [
"order_type",
"etd"
],
"additionalProperties": false
}
}
]
}
},
"required": [
"warehouse_id",
"operation_type",
"attributes"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"type": "object",
"properties": {
"attributes": {
"type": "object",
"properties": {
"order_type": { "const": "ORDER" }
},
"required": ["order_type"]
}
},
"required": ["attributes"]
},
"then": { "required": ["items"] }
}
]
}关键修正点解析：
通过这种方式，只有当整个 JSON 实例满足 attributes.order_type 为 "ORDER" 的条件时，顶层 items 属性才会被强制要求。
让我们使用修正后的 Schema 来验证不同类型的 JSON 数据。
{
"warehouse_id": "ARTW01",
"operation_type": "outbound",
"order_id": 41789301078,
"items": [
{"sku": "SKU001", "quantity": 10},
{"sku": "SKU002", "quantity": 5}
],
"attributes": {
"volume": 1350,
"etd": "2022-11-11T18:25:00Z",
"order_type": "ORDER"
}
}验证结果： 通过。因为 attributes.order_type 为 "ORDER"，且 items 属性存在并符合其自身的 Schema 定义。
{
"warehouse_id": "ARTW01",
"operation_type": "outbound",
"order_id": 41789301078,
"attributes": {
"volume": 1350,
"etd": "2022-11-11T18:25:00Z",
"order_type": "ORDER"
}
}验证结果： 失败。因为 attributes.order_type 为 "ORDER"，触发了根级别的 allOf 中的 then 条件，要求 items 属性必须存在，但实际数据中 items 缺失。
{
"warehouse_id": "ARTW01",
"operation_type": "inbound",
"order_id": 12345,
"attributes": {
"volume": 500,
"etd": "2023-01-01T10:00:00Z",
"order_type": "TRANSFER"
}
}验证结果： 通过。因为 attributes.order_type 为 "TRANSFER"，不满足 if 条件（order_type 为 "ORDER"），因此 then 中的 required: ["items"] 不会被应用。此时 items 属性不是必填项，即使缺失也符合 Schema。
以上就是JSON Schema 条件性必填属性：基于嵌套字段值精确控制顶层属性的详细内容，更多请关注php中文网其它相关文章！
每个人都需要一台速度更快、更稳定的 PC。随着时间的推移，垃圾文件、旧注册表数据和不必要的后台进程会占用资源并降低性能。幸运的是，许多工具可以让 Windows 保持平稳运行。
广告
收藏
收藏
收藏
Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号
130
