3. values.schema.json 入门：JSON Schema 标准简介，Helm 对 JSON Schema 的支持版本

在 Helm 应用交付中，values.yaml 是用户与 Chart 交互的核心接口。然而，纯 YAML 格式缺乏类型校验与约束机制，用户传入的错误数据类型或缺失字段往往在运行时才暴露。JSON Schema 正是解决这一问题的标准方案，而 Helm 从 3.x 版本开始内置了对 values.schema.json 的原生支持。

3.1 JSON Schema 标准简介

JSON Schema 是一种基于 JSON 格式的声明式语言，用于描述和验证 JSON 数据结构。它定义了一套关键字规则，可以约束数据的类型、范围、格式、必填字段以及嵌套结构。其核心价值在于：在数据消费之前完成校验，将错误拦截在配置阶段。

以下是最常用的 JSON Schema 关键字及其用途：

一个完整的 JSON Schema 示例（描述一个简单的 Deployment 配置）：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image", "replicas"],
  "properties": {
    "image": {
      "type": "string",
      "description": "容器镜像地址"
    },
    "replicas": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "env": {
      "type": "object",
      "additionalProperties": { "type": "string" }
    }
  },
  "additionalProperties": false
}

3.2 Helm 对 JSON Schema 的支持版本

Helm 对 JSON Schema 的支持经历了从无到有、从实验到稳定的演进过程。理解版本支持矩阵，有助于团队在升级 Helm 时评估 Schema 功能的可用性。

3.3 values.schema.json 文件结构与加载机制

在 Helm Chart 中，values.schema.json 必须放置在 Chart 包的根目录（与 Chart.yaml 同级）。Helm 在以下时机自动加载并执行校验：

• helm install：安装时校验用户传入的 --values / --set 参数
• helm upgrade：升级时校验新的 values 数据
• helm template：渲染模板时也会执行 Schema 校验（Helm 3.5+）

校验失败时，Helm 会输出明确的错误信息，指出违反约束的字段路径和期望类型，阻止安装或升级继续执行。

3.4 从 values.yaml 到 values.schema.json 的映射关系

编写 Schema 的核心工作是将 values.yaml 中的每个字段映射为 JSON Schema 的约束定义。以下是一个典型的映射对照：

3.5 多层级嵌套结构的 Schema 写法

实际 Chart 的 values 往往包含多层嵌套对象。JSON Schema 通过递归的 properties 结构来描述这种层级。以下是一个包含嵌套结构的 Schema 片段：

{
  "type": "object",
  "properties": {
    "global": {
      "type": "object",
      "properties": {
        "environment": { "type": "string", "enum": ["dev", "prod"] },
        "region": { "type": "string" }
      },
      "required": ["environment"]
    },
    "service": {
      "type": "object",
      "properties": {
        "port": { "type": "integer", "minimum": 1024, "maximum": 65535 },
        "targetPort": { "type": "integer" }
      },
      "required": ["port"]
    }
  },
  "required": ["global", "service"]
}

3.6 常见陷阱与最佳实践

• 陷阱一：忘记设置 additionalProperties — 默认允许未定义字段，用户拼写错误不会触发告警。建议在根对象和每个嵌套对象中显式设置为 false。
• 陷阱二：Schema 版本不匹配 — 使用 draft-04 语法在 Helm 3.10+ 中可能产生兼容性警告。推荐统一使用 draft-07。
• 陷阱三：忽略子 Chart 的 Schema — 如果主 Chart 依赖子 Chart，子 Chart 的 values.schema.json 不会自动合并到主 Schema 中。需要手动在父 Schema 中定义子 Chart 的 values 结构。
• 最佳实践： 在 CI 流水线中增加 helm lint --strict 步骤，该命令会同时校验 Schema 语法和 values 数据，提前发现 Schema 编写错误。