Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 38 ยท Testing and Security

Validating Values with values.schema.json

Add a JSON Schema to your chart with values.schema.json to reject bad values early, use required, enum and pattern, and see a runnable validator stand-in.

Values are the public interface of a chart, and users get them wrong all the time: replicaCount: "three", a misspelled key, a negative port. Without a guard, the mistake surfaces as a confusing Kubernetes error, or worse, as a silently ignored setting. Helm can validate values against a JSON Schema stored in the chart as values.schema.json.

How validation works

If a chart contains values.schema.json, Helm validates the final merged values (defaults, -f files, --set, parent values for a subchart) against it during install, upgrade, lint and template. A violation stops the operation with a message that names the offending path:

TEXT
Error: values don't meet the specifications of the schema(s) in the following chart(s):
webapp:
- replicaCount: Invalid type. Expected: integer, given: string
- image: tag is required

This is much earlier and clearer than a failed Deployment.

A first schema

JSON
{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image"],
  "properties": {
    "replicaCount": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "default": 2,
      "description": "Number of pods"
    },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": {
        "repository": { "type": "string", "minLength": 1 },
        "tag": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
        "pullPolicy": { "type": "string", "enum": ["Always", "IfNotPresent", "Never"] }
      },
      "additionalProperties": false
    },
    "service": {
      "type": "object",
      "properties": {
        "port": { "type": "integer", "minimum": 1, "maximum": 65535 }
      }
    }
  }
}

The keywords you will use most:

Keyword Purpose
type string, integer, number, boolean, object, array, null
required Keys that must be present (listed on the parent object)
enum Allowed values
minimum, maximum Numeric bounds
minLength, pattern String rules, with a regular expression
items The schema each array element must satisfy
additionalProperties: false Reject keys that are not declared, which catches typos
description, default Documentation, shown by tools and IDEs

Helm supports JSON Schema draft-07. Write required carefully: it applies to the merged values, so a key with a default in values.yaml satisfies it.

Catching typos with additionalProperties

By default, extra keys are allowed. That means replicaCont: 4 is silently ignored and the user wonders why nothing scales. Setting "additionalProperties": false on an object makes Helm reject unknown keys:

TEXT
- (root): Additional property replicaCont is not allowed

Use it on objects you fully control. Do not set it on blocks you pass straight through to Kubernetes (like resources or podAnnotations), where the key set is open ended. Also be careful at the root of a chart that has subcharts: the root object must allow the subchart names and global, or every install fails.

Python Stand-in: a tiny schema validator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Generating and testing the schema

Writing a long schema by hand is tedious. The helm-schema and helm schema plugins generate a first draft from values.yaml; review it and tighten required, enum and pattern. Keep the schema in the repository and test it:

YAML
# helm-unittest
- it: rejects a string replica count
  set:
    replicaCount: "three"
  asserts:
    - failedTemplate: {}

and add a CI step that runs helm lint --strict -f ci/*-values.yaml, since lint also validates against the schema.

Schemas in subcharts and required

Every chart can ship its own schema, and each is validated against its own section of the merged values. A parent does not need to repeat the rules of its subcharts. Besides schemas, templates can enforce rules with the required and fail functions:

YAML
image: {{ required "image.repository is required" .Values.image.repository }}
{{- if and .Values.ingress.enabled (not .Values.ingress.host) }}
{{- fail "ingress.host is required when ingress.enabled is true" }}
{{- end }}

Use the schema for shape (types, ranges, enums) and required/fail for cross-field rules that JSON Schema handles awkwardly.

Python Stand-in: cross-field rule with fail

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical tips

  • Add description fields; editors (and tools like helm-docs) turn them into documentation.
  • Make nullable values explicit with "type": ["string", "null"].
  • A schema is part of your API: tightening it is a breaking change, so bump the major version.
  • Test with a deliberately bad values file so you see the error message users will see.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Against which values does Helm validate the schema?

    Validation happens on the fully merged values.
  2. 2. Which setting turns a misspelled key into an error?

    With additionalProperties false, undeclared keys are rejected.
  3. 3. When is the required template function a better fit than the schema?

    Cross-field rules such as host required when ingress is enabled are easier in templates.

Summary

  • values.schema.json (JSON Schema draft-07) validates merged values on install, upgrade, lint and template.
  • Use type, required, enum, bounds, pattern, and additionalProperties: false on objects you control.
  • Combine the schema (shape) with required/fail (cross-field rules); treat the schema as part of the chart's API.

Next: Chart Security and Provenance