如何在单个JSON Schema中支持Helm子chart两种顶层值结构的校验

需求背景 #

编写Helm子chart的JSON Schema时，需要用同一份Schema同时覆盖两种校验场景：

1. 校验子chart自身项目内的values.yaml，配置直接写在顶层：

# 子chart内的values.yaml
propOne:
  derp: 123
  herp: abc

2. 校验父chart引用子chart时的values.yaml，所有子chart配置嵌套在顶层mysubchart字段下：

# 父chart内的values.yaml
mysubchart:
  propOne:
    derp: 123
    herp: abc

常见错误写法 #

初始编写的Schema无法同时兼容两种场景，两份文件均校验失败，错误示例如下：

{
  "$defs": {
    "mychart": {
      "$schema": "http://json-schema.org/schema#",
      "title": "test",
      "description": "test",
      "type": "object",
      "required": ["propOne", "propTwo"],
      "properties": {
        "propOne": {
          "description": "字段说明",
          "type": "string"
        },
        "propTwo": {
          "description": "字段说明",
          "type": "string"
        }
      }
    }
  },
  "oneOf": [
    {
      "$ref": "#/$defs/mychart"
    },
    {
      "properties": {
        "mychart": {
          "$defs": "#/$defs/mychart"
        }
      }
    }
  ]
}

问题原因 #

错误点共有三处：

1. 嵌套分支的属性引用错误，应该用$ref指向预定义的配置结构，而非$defs
2. 父chart适配分支未声明required: ["mysubchart"]，导致匹配逻辑混乱，无法正确识别嵌套场景
3. 嵌套字段名拼写错误，应该对应子chart的名称mysubchart而非mychart

最终可用实现 #

修改后的Schema可同时适配两种场景，同时支持编辑器自动补全、helm lint校验：

{
  "$schema": "http://json-schema.org/schema#",
  "$defs": {
    "mysubchartSpec": {
      "title": "mysubchart配置规范",
      "description": "mysubchart的values配置定义",
      "type": "object",
      "required": ["propOne", "propTwo"],
      "properties": {
        "propOne": {
          "description": "propOne配置项，包含derp和herp两个子字段",
          "type": "object",
          "required": ["derp", "herp"],
          "properties": {
            "derp": {"type": "integer"},
            "herp": {"type": "string"}
          }
        },
        "propTwo": {
          "description": "propTwo配置项，字符串类型",
          "type": "string"
        }
      }
    }
  },
  "oneOf": [
    // 匹配子chart自身的values.yaml
    {
      "$ref": "#/$defs/mysubchartSpec"
    },
    // 匹配父chart内嵌套的子chart配置
    {
      "type": "object",
      "required": ["mysubchart"],
      "properties": {
        "mysubchart": {
          "$ref": "#/$defs/mysubchartSpec"
        }
      },
      // 允许父chart存在其他子chart的配置字段，避免误校验
      "additionalProperties": true
    }
  ]
}

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