Learn Helm Chart - Schema Validation with JSON Schema

#Introduction

After episode 12, where we covered hooks — Helm's mechanism for running actions at critical points in a release's lifecycle — in this episode we cover something that may not look glamorous but is precisely what separates amateur charts from production-grade ones: schema validation with JSON Schema.

Think about the moment you consume a public chart. You open values.yaml, change some keys, and run helm install. A few seconds later Helm renders the templates, sends the manifests to the Kubernetes API server, and — if you mis-typed a data type or forgot a required field — you only find out after getting a cryptic error from Kubernetes, or worse, an application running in a wrong state. That's the problem JSON Schema solves: validation happens before templates are rendered, with clear, human-readable error messages.

Why does this matter in the real world? A chart is used by many teams, sometimes teams that have no idea what's inside values.yaml. They'll copy examples from the README, tweak them, and hope for the best. Without a schema, every small mistake — replicas: "3" when it must be a number, a misspelled storageClass, an ingress.enabled that isn't a boolean — becomes a time bomb that explodes long after install. With a schema, those mistakes are rejected at the front door with a message like "replicas: Invalid type. Expected: integer, given: string". Not only does a schema protect chart users, it also protects you as a chart author from hundreds of support tickets that should never have existed.

#Main Discussion

#What Is values.schema.json and How It Works

JSON Schema is an open standard for describing and validating JSON data structures. Because values.yaml is essentially represented as JSON (YAML is a JSON superset), Helm uses this standard to validate the values users provide before the chart is rendered.

When your chart contains a values.schema.json file at the chart's root directory (alongside values.yaml), Helm automatically validates every value to be used — both the defaults in values.yaml and the overrides given via --set, --values, or -f — against that schema. Validation happens on every helm install, helm upgrade, and helm template too, where applicable. If a value doesn't match the schema, the operation stops immediately with an error message, before a single manifest is sent to the cluster.

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1
    },
    "image": {
      "type": "object",
      "properties": {
        "repository": { "type": "string" },
        "tag": { "type": "string" }
      }
    }
  },
  "required": ["replicaCount", "image"]
}

Note that the schema declares a $schema pointing to a specific draft version. Helm supports JSON Schema draft-07 and draft-2020-12 (since Helm 3.14), and adjusts validation to the declared version. This matters because there are syntax differences — for example, the condition syntax differs between drafts — and you must stay consistent with the version you choose.

Validation itself is performed by Helm's internal Go library, not by calling an external tool. As a result, all functions supported by that library are available — and the most essential JSON Schema features (which we'll cover in the properties section) are all fully supported.

#Validation Properties: Data Types and Value Constraints

The core of a schema is describing the shape of data each key is allowed to accept. Helm rejects values that violate that description. Here are the properties used most often:

Three of these deserve deeper discussion because they cause the most confusion.

First, type for numbers. JSON Schema distinguishes integer (whole numbers) and number (can be decimal). A YAML value like replicas: 3 is recognized as an integer, but replicas: 3.5 would pass number validation while being rejected by integer. Even trickier: replicas: "3" — with quotes — is a string, and will be rejected by "type": "integer". This is one of the most common mistakes, and a schema is exactly what catches it.

Second, additionalProperties. By default, JSON Schema allows extra keys beyond those defined in properties. If you want your chart to be strict — rejecting unknown keys so a typo like replicaCountt is caught immediately — set "additionalProperties": false. But be careful: this also means every time you add a new key to values.yaml, the schema must be updated, or the install fails. This trade-off is fair for strict internal charts, but not always suitable for public charts that want flexibility.

Third, items. To validate array elements, items defines the schema of each element. For a simple array like a list of strings, { "type": "array", "items": { "type": "string" } } is enough. For an array of objects — for example, a list of volumes or sidecars — each element is an object with its own properties and required.

{
  "type": "object",
  "properties": {
    "extraVolumes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "path": { "type": "string" }
        },
        "required": ["name", "path"],
        "additionalProperties": false
      }
    }
  }
}

#Automatic Validation and Clear Error Messages

When validation fails, Helm stops the operation and displays a complete list of errors. Because validation runs per-key, you get all violations at once, not one at a time. This helps a lot: users fix every mistake in one iteration instead of bouncing back and forth between install-fail and install-fail.

Error: values don't meet the specifications of the schema(s) in the following chart(s):
  - my-app:
    - replicaCount: Invalid type. Expected: integer, given: string
    - image.tag: Pattern mismatch. Pattern: ^v?[0-9]+\.[0-9]+\.[0-9]+$, given: latest
    - service.port: Less than minimum of 1. Got: 0

It's important to understand: this validation checks the final values the chart will use — the merged result of values.yaml defaults, override files, and --set. So a schema doesn't just protect against wrong overrides; it also protects against a values.yaml default that turns out to be inconsistent with the schema. That's a double safety net.

#Advanced Schemas: Conditional and Logical Composition

Basic schemas are enough for many charts, but real cases often need validation that depends on other values. That's where JSON Schema's logic properties come in.

oneOf, anyOf, and allOf let you compose complex conditions:

• allOf — all sub-schemas must be valid (useful for stacking validations).
• anyOf — at least one sub-schema must be valid.
• oneOf — exactly one sub-schema must be valid (often used to enforce exclusive choices).

A real example: a chart supporting two database modes, embedded PostgreSQL or external. If database.external.enabled is true, then database.external.host and database.external.port are required. Such a conditional can be expressed with oneOf combining two conditions:

{
  "type": "object",
  "properties": {
    "database": {
      "type": "object",
      "properties": {
        "embedded": { "type": "object" },
        "external": {
          "type": "object",
          "properties": {
            "enabled": { "type": "boolean" },
            "host": { "type": "string" },
            "port": { "type": "integer", "minimum": 1 }
          }
        }
      },
      "oneOf": [
        { "required": ["embedded"] },
        {
          "required": ["external"],
          "properties": {
            "external": {
              "required": ["enabled", "host", "port"]
            }
          }
        }
      ]
    }
  }
}

Besides composition, there's the dependencies property that makes validation of one field depend on the presence of another field. For example, if ingress.enabled is true, the ingress.host field becomes required. In JSON Schema draft-07 this is written with a dependencies block at the object level:

{
  "type": "object",
  "properties": {
    "ingress": {
      "type": "object",
      "properties": {
        "enabled": { "type": "boolean", "default": false },
        "host": { "type": "string" }
      },
      "dependencies": {
        "enabled": { "required": ["host"] }
      }
    }
  }
}

Note the conceptual difference between oneOf/anyOf/allOf (logical composition) and dependencies (conditional validation between fields). oneOf enforces "exactly one branch," while dependencies enforces "if field A exists/has a certain value, then field B must exist." Both are often used together for complex enterprise chart schemas.

#Schema Benefits for Chart Users and Tooling

A schema doesn't just reject wrong values; it also empowers tooling that makes the chart user experience much better.

First, clear error messages. Compared to cryptic template errors or Kubernetes errors, schema validation messages tell you exactly which key is wrong and what's expected. That cuts debugging time from minutes to seconds.

Second, automatic documentation. The description property on every schema field can become documentation read by the IDE. Instead of digging through values.yaml and scattered comments, users can see a field's explanation right while typing.

Third, IDE autocompletion. Because schemas are an open standard, editors like VS Code (through the YAML extension) can read values.schema.json and provide autocompletion for every valid key, including values allowed by enum. This dramatically reduces typos and misspellings — users don't have to memorize the values.yaml structure.

replicaCount: 3
image:
  repository: nginx
  tag: 1.27.0
service:
  port: 80

In line with the same keys, the schema can provide a per-field description:

{
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of application replicas. Minimum 1, must not be a string."
    },
    "service": {
      "type": "object",
      "properties": {
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535,
          "description": "The exposed Service port."
        }
      }
    }
  }
}

This way, one schema file serves a dual purpose: as the contract enforcer at install time and as the interactive documentation base in the editor.

#Best Practices and Common Pitfalls

Like every tool, JSON Schema has traps that can create a bad experience if not understood. Here are the most common ones.

Pitfall one: a schema stricter than the values.yaml defaults. If the schema sets "required": ["replicaCount"] but values.yaml doesn't have that key, helm install fails immediately even when the user does nothing. Always make sure every required key exists in values.yaml, and every default already passes the schema. The fastest way to verify: run helm template with a pure values.yaml (no overrides) — if that fails, your chart is broken from the start.

Pitfall two: additionalProperties: false that's too strict at the top level. For large charts with dozens of keys, closing the whole schema with additionalProperties: false at the root means every key addition forces a schema update. A better strategy: apply additionalProperties: false only to small objects whose key set is genuinely limited, and leave the top level open.

Pitfall three: forgetting that YAML can technically hold non-string keys. JSON Schema treats object keys as strings, so that's fine. But make sure the values you pass with --set match the types in the schema. --set replicaCount=3 produces an integer, while --set replicaCount="3" produces a string. Type consistency between CLI overrides and the schema is the user's responsibility, and the schema is what enforces it.

Pitfall four: not testing the schema. A schema is code, and code needs testing. Use helm template with various value combinations — valid and invalid — to make sure the schema rejects wrong values and accepts right ones. Some teams even write dedicated tests for schemas, for example with helm-unittest, which we'll cover in the next episode, episode 14.

#Conclusion

In this episode we covered how values.schema.json turns chart values from "anything goes" into a "guaranteed contract": the basic schema structure, validation properties like type, required, enum, pattern, minimum/maximum, items, and additionalProperties; automatic validation running before templates render with clear error messages; advanced schemas with oneOf/anyOf/allOf and dependencies for conditional validation; and the real benefits for chart users in the form of documentation and IDE autocompletion. Most importantly, you now understand that a schema is the first line of defense that stops configuration errors from reaching the cluster.

In the next episode, episode 14, we cover testing charts systematically — from helm test, template render unit tests with helm-unittest, manifest validation with kubeconform, to CI integration with chart-testing. The combination of schemas (value validation) and testing (output validation) is what makes your charts worthy of publication and trust across many teams. Keep your spirits up!