Validate Helm values.yaml with JSON Schema (2026)

Helm’s values.yaml can be validated against a JSON Schema, but it’s not a built-in feature of Helm itself; you need to integrate it.

Let’s see Helm validate a chart’s values.yaml against a JSON schema.

Here’s a simple Helm chart with a values.yaml and a values.schema.json:

my-chart/
  Chart.yaml
  values.yaml
  values.schema.json
  templates/
    deployment.yaml

my-chart/values.yaml:

replicaCount: 1
image:
  repository: nginx
  tag: stable
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80

my-chart/values.schema.json:

{
  "type": "object",
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 0
    },
    "image": {
      "type": "object",
      "properties": {
        "repository": {
          "type": "string"
        },
        "tag": {
          "type": "string"
        },
        "pullPolicy": {
          "type": "string",
          "enum": ["IfNotPresent", "Always", "Never"]
        }
      },
      "required": ["repository", "tag"]
    },
    "service": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": ["ClusterIP", "NodePort", "LoadBalancer"]
        },
        "port": {
          "type": "integer",
          "minimum": 1,
          "maximum": 65535
        }
      },
      "required": ["type", "port"]
    }
  },
  "required": ["replicaCount", "image", "service"]
}

To validate this, we’ll use the ajv-cli tool. First, install it globally:

npm install -g ajv-cli

Now, you can run the validation from the directory containing your my-chart directory:

ajv validate --schema-from-file my-chart/values.schema.json --data-from-file my-chart/values.yaml

If the values.yaml is valid, you’ll see:

my-chart/values.yaml is valid

If it’s invalid, ajv-cli will report the specific errors:

# Example with an invalid pullPolicy
echo "replicaCount: 1\nimage:\n  repository: nginx\n  tag: stable\n  pullPolicy: InvalidPolicy" > my-chart/values.yaml
ajv validate --schema-from-file my-chart/values.schema.json --data-from-file my-chart/values.yaml

Output:

my-chart/values.yaml is NOT valid
my-chart/values.yaml:
  /image/pullPolicy should be one of [IfNotPresent Always Never]

This process allows you to define strict contracts for your Helm chart values, catching configuration errors early. The values.schema.json file acts as the single source of truth for what constitutes a valid configuration for your chart, enforced independently of Helm’s templating engine.

The most surprising thing about this approach is that Helm doesn’t natively support schema validation, forcing you to adopt external tooling. While helm lint checks for some basic syntax and template errors, it doesn’t understand the semantic meaning or acceptable ranges of your values. JSON Schema provides this semantic layer, ensuring that even if your values.yaml is syntactically correct YAML and your templates render without error, the configuration itself is meaningful and safe. It’s a crucial step for production-ready Helm charts where configuration correctness is paramount.

The ajv-cli tool interprets the JSON Schema and compares it against the provided YAML data (after it’s parsed into a JSON-like structure). It walks the data structure, checking each key against its corresponding definition in the schema. For instance, when it encounters image.pullPolicy, it looks up properties.image.properties.pullPolicy in the schema. If the value "InvalidPolicy" is not present in the enum array ["IfNotPresent", "Always", "Never"], the validation fails, and an error is reported detailing the path (/image/pullPolicy) and the reason for failure. This systematic comparison ensures adherence to the defined structure and constraints.

A common pattern is to integrate this validation into your CI/CD pipeline. Before a Helm chart is deployed, a job can run ajv validate. If the validation fails, the pipeline stops, preventing invalid configurations from reaching your cluster. You can also automate the generation of values.schema.json from existing values.yaml files or more complex OpenAPI specifications, though manual definition is often clearer for chart-specific configurations.

The real power comes from the required fields in the schema. If you forget to define image.tag in your values.yaml, the schema validation will explicitly tell you it’s missing, whereas Helm would simply render a template with an undefined variable, likely leading to a Kubernetes error later.

The next step is to explore how to integrate this validation automatically into your Helm release process using tools like Argo CD or Flux CD.