helm-schema

CLI reference

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

CLI reference#

helm-schema is a single command: one positional argument (the chart) plus flags. There are no subcommands. The generated schema goes to standard output unless --output is given; diagnostics go to standard error.

helm-schema [OPTIONS] <CHART_DIR>

Run helm-schema --help for the authoritative, version-specific summary.

Argument#

Argument	Description
`<CHART_DIR>`	Chart directory or packaged chart archive (`.tgz`/`.tar.gz`) to analyze. Required.

Output#

Flag	Description
`-o`, `--output <FILE>`	Write the schema to a file; standard output is used when absent.
`--compact`	Compact JSON instead of the default pretty-printed output.
`--strip-descriptions`	Remove JSON Schema `description` annotations. Schema-aware: a property literally named `description` is kept.
`--profile <full\|lean>`	Select emitted validation detail. `full` is the default. `lean` omits document-level conditional validation to reduce Helm validator compilation cost and only widens acceptance.
`--keep-refs`	Leave file/URL `$ref` strings as-is. By default external refs are resolved into root-level `$defs` so the output is self-contained. Conflicts with `--inline-refs`.
`--inline-refs`	Fully inline resolved file/URL `$ref`s instead of writing `$defs`.
`--no-minimize`	Keep repeated subtrees inline instead of interning them into root-level `$defs`. Interning is on by default.

See Output for what these produce.

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.

Template analysis

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

Template analysis#

The core of helm-schema is reading the chart’s templates. This page explains what it extracts and how the control flow around a value shapes the schema — which is what lets you predict the output.

Value extraction#

Every .Values.* path that appears in render logic is collected — from manifests, from _helpers.tpl helpers, and from YAML fragments loaded via .Files.Get with a literal path. It reads the template’s real structure, so quoting, pipelines, nested calls, and whitespace trimming ({{-/-}}) are all handled correctly rather than approximated.

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:

Output

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

Output#

helm-schema emits a single JSON Schema, Draft-07, rooted at the Helm values object and written to standard output (or --output <FILE>). This page describes the shape of that output and the flags that control it.

Anatomy#

{
 "$schema": "http://json-schema.org/draft-07/schema#",
 "$defs": { "…": "…" },
 "additionalProperties": false,
 "properties": { "…": "…" },
 "allOf": [ "…" ],
 "type": "object",
 "x-helm-schema-generated": true
}

$schema — always Draft-07. This is the dialect Helm validates against.
type: object and additionalProperties: false — the root is the values object, and only keys the chart actually consumes are allowed. Unrecognized keys are rejected, which is what catches typos.
properties — one entry per value path the chart reads, typed from template use and resolved resource fields.
allOf — conditional structure produced from template control flow (if/then, guard-scoped constraints). See Template analysis.
$defs — interned subtrees shared by $ref (see Minimization), plus a few reusable building blocks such as helm-truthy.
x-helm-schema-generated: true — a marker identifying the file as machine-generated.

Recurring building blocks#

Some $defs entries appear across many charts:

Values & defaults

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

Values & defaults#

Beyond where a value is used, helm-schema looks at how the chart defaults it — both the composed values.yaml document and default expressions in templates.

The composed values document#

Before analysis, the tool builds one effective values document:

the root values.yaml,
each subchart’s defaults merged under its dependency key,
subchart global merged into the top-level global.

This composed document seeds the schema’s shape and supplies the default value for each path. Use --no-subchart-values to omit vendored subchart defaults under charts/ (see Subcharts).

Diagnostics

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

Diagnostics#

Anything helm-schema can’t resolve is reported as a diagnostic on standard error, never silently guessed. Diagnostics never appear in the schema (which goes to stdout), so they don’t interfere with piping the output to a file.

Format#

helm-schema ./mychart --diag-format text # default
helm-schema ./mychart --diag-format json

text (default): human-readable lines prefixed with warning: or info:.
json: one JSON object per line. Each is a Diagnostic — a discriminated union tagged on a "type" field. After a successful CLI parse, every stderr line is such an object.

CLI parse errors are not part of the JSON contract: clap writes a plain-text usage error before the runtime starts. JSON consumers distinguish the two by exit code — a non-zero exit with no JSON line emitted means a parse error.

Kubernetes schemas

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

Kubernetes schemas#

When a value flows into a built-in Kubernetes resource field, helm-schema types it from the upstream Kubernetes JSON schema for that resource. This is what turns spec.replicas into an int32 with the API’s own description, or a resources block into the full ResourceRequirements shape.

Schemas are fetched on demand from the upstream catalog and cached locally. The upstream source is authoritative; the cache only makes repeat lookups fast.

Choosing the version#

helm-schema ./mychart --k8s-version v1.34.0

--k8s-version selects the Kubernetes minor version whose schemas are consulted. The default is v1.35.0.

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.

Caching

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

Caching#

helm-schema caches the Kubernetes and CRD schemas it fetches so repeat runs are fast and can run offline. The cache is purely a speed optimization — never a source of truth.

The upstream schema source is always authoritative; the cache is fetch-on-miss. A run against a cold cache and a run against a warm cache produce the same schema. If a code path could answer differently depending on what happens to be cached, that is a bug — the tool is designed so it can’t.

CRD schemas

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

CRD schemas#

Charts that deploy custom resources — a ServiceMonitor, a Certificate, an operator’s CRD — need schemas that aren’t part of the built-in Kubernetes API. helm-schema resolves those against a CRD catalog, using the same lookup order as built-in resources, with your local overrides at the top.

The lookup order for any grouped resource is:

local overrides (--crd-override-dir) — authoritative,
the CRD catalog (fetched and cached, per version),
upstream Kubernetes JSON schemas (for built-in kinds).

Version lookup: strict vs loose#

helm-schema ./mychart --crd-version-lookup strict # default
helm-schema ./mychart --crd-version-lookup loose

strict (default) consults only the exact (group, kind, version) the chart pinned. A CRD version is never substituted — pinning v1 and getting a v1alpha1 schema would be wrong.
loose resolves identically (still no substitution), but additionally scans the local cache for other versions of the same (group, kind). When the requested version is missing but others are present, it emits a CrdVersionAvailableAtOtherVersions hint — informational only.

--strict-crd-version is a short alias for --crd-version-lookup=strict, kept for symmetry with the other strict flags.

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:

Subcharts & dependencies

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

Subcharts & dependencies#

helm-schema analyzes a chart together with its vendored dependencies, so the schema covers values consumed by subcharts too.

Discovery#

Chart discovery reads Chart.yaml (and Chart.template.yaml) and walks dependencies under charts/ — both unpacked directories and packaged .tgz/.tar.gz archives. Each dependency’s templates are analyzed, and the values it consumes appear in the schema under its dependency key.

Composed values and `global`#

The effective values document merges:

the parent chart’s values.yaml,
each subchart’s defaults, nested under its dependency key,
each subchart’s global values, merged into the top-level global.

That mirrors how Helm itself composes values, so a value a subchart reads from .Values.global.* and one the parent sets under subchartName.* both land where the schema expects them.

Schema overrides

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

Schema overrides#

Static analysis can’t recover everything — a value assembled through a dynamically-computed key, a field an outer pipeline injects at render time, or a type the templates simply never pin down. For those residual cases, post-process the generated schema with one or more override schemas.

helm-schema ./mychart \
 --override-schema ../schemas/injected-keys.override.json \
 --override-schema ./schema-override.json \
 --output values.schema.json

--override-schema is repeatable. Files are applied in the order given, each merged on top of the previous result. A common split is a shared cross-chart override (for example, top-level keys an outer templating pipeline injects and helm-schema can’t see in values.yaml) followed by a chart-specific override.

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.

helm-schema

CLI reference

CLI reference#

Argument#

Output#

Introduction

Introduction#

Template analysis

Template analysis#

Value extraction#

Installation

Installation#

Homebrew#

From crates.io#

Output

Output#

Anatomy#

Recurring building blocks#

Values & defaults

Values & defaults#

The composed values document#

Diagnostics

Diagnostics#

Format#

Kubernetes schemas

Kubernetes schemas#

Choosing the version#

Quick start

Quick start#

1. Point it at a chart#

Caching

Caching#

CRD schemas

CRD schemas#

Version lookup: strict vs loose#

How it works

How it works#

It combines three signals#

Subcharts & dependencies

Subcharts & dependencies#

Discovery#

Composed values and global#

Schema overrides

Schema overrides#

Continuous integration

Continuous integration#

Verify a committed schema#

FAQ

FAQ#

Is it production-ready?#

Does it need Helm, or a cluster?#

Composed values and `global`#