Reference on 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.

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:

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.

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.