两种条件API响应通用JSON Schema编写及校验问题咨询

问题1解答 #

不需要编写两个独立Schema，完全可以用单个通用JSON Schema同时适配两种响应结构。JSON Schema提供的组合关键字天然支持这类互斥结构的校验需求。

问题2解答 #

你之前的测试不符合预期，核心是修改后的Schema第一个分支只要求intervalData必填，没有强制intervalTotals同时存在，也没有明确禁止另一种结构的字段出现。
正确的写法需要在oneOf的每个分支里同时明确「必填字段」和「禁写字段」，就能实现两种组合完全互斥的校验效果，参考如下完整Schema：

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "oneOf": [
    {
      "required": ["intervalData", "intervalTotals"],
      "not": { "required": ["multiFilterData"] }
    },
    {
      "required": ["multiFilterData"],
      "not": { "required": ["intervalData", "intervalTotals"] }
    }
  ],
  "properties": {
    "intervalData": {
      "type": "array",
      "additionalItems": false,
      "items": {
        "type": "object",
        "required": ["timestamp", "result"],
        "properties": {
          "timestamp": { "type": "string" },
          "result": {
            "type": "object",
            "required": ["Attempts"],
            "properties": {
              "Attempts": { "type": "integer" }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    },
    "intervalTotals": {
      "type": "object",
      "required": ["Attempts"],
      "properties": {
        "Attempts": { "type": "integer" }
      },
      "additionalProperties": false
    },
    "multiFilterData": {
      "type": "array",
      "additionalItems": false,
      "items": {
        "type": "object",
        "required": ["filter", "intervalData"],
        "properties": {
          "filter": {
            "type": "object",
            "required": ["id"],
            "properties": {
              "id": { "type": "integer" }
            },
            "additionalProperties": false
          },
          "intervalData": {
            "type": "object",
            "required": ["timestamp", "result"],
            "properties": {
              "timestamp": { "type": "string" },
              "result": {
                "type": "object",
                "required": ["Attempts"],
                "properties": {
                  "Attempts": { "type": "integer" }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

关键规则说明

1. 第一个分支要求必须同时存在intervalData和intervalTotals，且绝对不能出现multiFilterData，只要缺少两个必填字段中的任意一个，或者出现了multiFilterData，就不会命中该分支
2. 第二个分支要求必须存在multiFilterData，且绝对不能出现intervalData和intervalTotals，只要出现了两个单条件场景的字段中的任意一个，就不会命中该分支
3. oneOf关键字要求必须且只能命中其中一个分支，只要两种结构同时存在、或者缺少对应必填字段，都会直接校验失败，完全符合需求。

内容的提问来源于stack exchange，提问作者John Shepard