Documentation on helm-schema

Introduction

Mon, 01 Jan 0001 00:00:00 +0000

Introduction#

helm-schema generates a JSON Schema for a Helm chart’s values.yaml by statically analyzing the chart’s templates. You point it at a chart directory (or a packaged .tgz), and it prints a Draft-07 schema:

helm-schema ./mychart --output mychart/values.schema.json

Helm reads a values.schema.json placed next to values.yaml automatically and validates user-supplied values against it during install, upgrade, lint, and template. A good schema turns a class of “it rendered, but wrong” mistakes into an error at submit time.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Installation#

helm-schema is a single self-contained binary. There is nothing to configure to get started — the Kubernetes and CRD schemas it consults are fetched on demand and cached.

Homebrew#

brew install --cask romnn/tap/helm-schema

This installs a prebuilt binary from the romnn/homebrew-tap tap. Prebuilt binaries are published for Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), and Windows (x86_64, aarch64).

From crates.io#

The CLI ships from the helm-schema-cli crate. The binary it installs is named helm-schema:

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

Quick start#

This walks through a first run and how to read the output. It assumes helm-schema is installed.

1. Point it at a chart#

The only required argument is the chart — a directory or a packaged .tgz/.tar.gz:

helm-schema ./mychart

The generated schema is written to standard output by default, so you can redirect it or inspect it directly. To write it where Helm will find it, use --output:

helm-schema ./mychart --output mychart/values.schema.json

Helm automatically validates values against a values.schema.json next to values.yaml on install, upgrade, lint, and template.

How it works

Mon, 01 Jan 0001 00:00:00 +0000

How it works#

You don’t need to know any of this to use helm-schema — but it explains why the schema is more accurate than one derived from values.yaml, and what to expect from the output.

The short version: it reads your chart the way Helm does, follows each value to where it is actually used, and types it from what’s expected there.

It combines three signals#

For every value, helm-schema looks at:

Continuous integration

Mon, 01 Jan 0001 00:00:00 +0000

Continuous integration#

There are two ways to use helm-schema in CI: commit the generated schema and verify it stays in sync, or generate it fresh as part of packaging. Both rely on the output being deterministic.

Verify a committed schema#

The most common setup commits values.schema.json next to values.yaml (so Helm validates against it) and has CI fail if the committed file drifts from what the chart now produces.

name: helm-schema
on: [push, pull_request]

jobs:
 schema:
 runs-on: ubuntu-24.04
 steps:
 - uses: actions/checkout@v4

 - name: Install helm-schema
 run: cargo install --locked helm-schema-cli

 - name: Regenerate the schema
 run: helm-schema ./charts/mychart --output ./charts/mychart/values.schema.json

 - name: Fail if it drifted
 run: git diff --exit-code -- ./charts/mychart/values.schema.json

If the schema is out of date, git diff --exit-code fails and prints the diff. Contributors run the same helm-schema … --output … command locally to update it.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

FAQ#

Is it production-ready?#

helm-schema is alpha. It is useful and works for many charts, but Helm templating and YAML composition have many edge cases — whitespace trimming, dynamic keys, helper indirection, runtime-only behavior — and some charts will need manual overrides or will surface an occasional incorrect or missing inference. Treat the output as a strong starting point you can review and tighten, not an infallible contract.

Does it need Helm, or a cluster?#

No to both. It parses templates itself (it does not shell out to helm) and never contacts a Kubernetes API server. “Resource-aware” means it consults published JSON schemas for the resources a chart renders, not a live cluster.