Can values.schema.json stop risky Helm settings before install?

Yes, within limits. A values.schema.json file in a chart lets Helm reject values that break your rules, such as a missing field or a wrong type, before anything reaches the cluster. It validates the final merged values, so it also catches overrides passed on the command line.

What the schema does

The Helm documentation describes an optional values.schema.json file that imposes structure on the chart's values. It is a JSON Schema document. Helm applies it during four commands: install, upgrade, lint and template.

One detail matters for security. The schema is applied to the final values object, not just to the values.yaml file. A value passed with the set flag at install time is checked as well. The documentation adds that the final values are checked against all subchart schemas too, so restrictions on a subchart cannot be sidestepped by a parent chart.

What you can enforce

JSON Schema can express rules that map directly to safer defaults:

• Required fields, so an installer cannot omit a setting you depend on.
• Types, so a number is not passed as a string and silently ignored.
• Allowed values through enumerations, such as a fixed list of permitted service types or log levels.
• Ranges, such as a minimum and maximum replica count or valid port range.
• Patterns for strings, such as requiring an image reference to include a digest.
• Forbidding unknown keys, so a typo in a security setting fails instead of doing nothing.

That last one is underrated. A misspelled key such as a securty block is, without a schema, simply ignored, and the chart runs with the default you thought you had overridden.

A small example

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image"],
  "properties": {
    "image": {
      "type": "object",
      "required": ["repository", "digest"],
      "properties": {
        "repository": { "type": "string" },
        "digest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
      }
    },
    "replicaCount": { "type": "integer", "minimum": 1, "maximum": 10 }
  }
}

With this schema, an install without a digest fails fast with a validation error rather than deploying a movable tag.

Where it stops

A schema checks the shape of values. It does not read your templates. If a template ignores a value, or hardcodes a privileged setting, the schema cannot see that. It also cannot know what is inside the image you reference.

It also depends on the chart author. If you consume a third-party chart without a schema, you get none of these checks. You can add a wrapper chart that depends on the original and carries its own schema, because parent and subchart schemas are both enforced.

Treat the schema as one layer next to policy checks on rendered manifests. A schema says the values look right. A policy on the rendered output says the result is acceptable.

A rollout path

1. Start with required fields and types only. Run lint in CI.
2. Add enumerations for settings that have a small safe set.
3. Add the pattern for image digests once your pipeline produces them.
4. Turn on strict unknown keys after a release cycle, so you have time to fix typos.
5. Add a CI step that renders the chart and scans the output.

Where a scanner fits

A schema stops bad inputs. A scanner finds known problems in what those inputs select. Safeguard's dependency scanning and SBOM generation can inventory the images and charts a values file points at, and policy gates can block a pull request that selects something your rules forbid. A free scan is at gold.safeguard.sh/scan.

Quick check

Sources

• Charts, Helm documentation

Last reviewed: 19 October 2026.