Guide on helm-schema

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.

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).

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.

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.

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.

Guide on helm-schema

Template analysis

Template analysis#

Value extraction#

Values & defaults

Values & defaults#

The composed values document#

Kubernetes schemas

Kubernetes schemas#

Choosing the version#

CRD schemas

CRD schemas#

Version lookup: strict vs loose#

Subcharts & dependencies

Subcharts & dependencies#

Discovery#

Composed values and global#

Schema overrides

Schema overrides#

Composed values and `global`#