Helm Values Schema Validator

Introduction:

Many Helm release failures start as small value mistakes: a port typed as a string, a misspelled image key, a service type outside the allowed set, or an override that never reaches the template the operator expected. Helm values make charts flexible, but that flexibility means a chart can accept almost any YAML shape unless the chart author writes down the contract.

A values.schema.json file is that contract. It describes the allowed shape of the values object that Helm validates before rendering chart templates. The schema can require important keys, restrict types, close typo-prone objects, limit numeric ranges, allow only known strings, and document what each value controls. For chart users, it turns confusing template failures into earlier configuration errors. For chart maintainers, it makes the supported configuration surface easier to review as the chart evolves.

Good values schemas are strict in places where mistakes are expensive and flexible where chart consumers need extension points. Closing an object with additionalProperties: false catches typos under image, service, ingress, and persistence settings, but the same rule can be too restrictive for labels, annotations, and application-specific maps. Required keys should represent real deployment needs, not just author preference. Ranges and enumerations are most useful where Kubernetes or the chart's templates expect a narrow set of values.

Schema validation is also a documentation practice. Descriptions attached to properties help humans understand what a value does, and they give generated chart docs or editors better context. Defaults still belong in values.yaml; a schema default is an annotation, not a reliable way to change the values object during validation.

A passing values schema does not prove that a release will work in a cluster. It does not contact the Kubernetes API server, confirm image availability, check RBAC, validate CRD presence, or evaluate admission policy. It is an early configuration gate that works best beside helm lint, template rendering, dry-run workflows, chart tests, and environment-specific review.

How to Use This Tool:

Check a values file and schema together, then read hard failures before using the CI snippet or hygiene findings.

1. Choose Validation profile. Use Helm CI gate for release automation, Schema authoring review for chart-maintainer cleanup, or Override values review when you are checking user-supplied values against a third-party chart.
2. Paste, drop, or browse the values.yaml content. Use the chart defaults, a merged override file, or the values fragment that represents the release under review. If YAML parsing fails, fix indentation, quoting, duplicate keys, or scalar syntax before reading schema failures.
3. Paste, drop, or browse values.schema.json. Use Format JSON when the schema is hard to scan. If JSON parsing or schema compilation fails, correct the schema before judging the values file.
4. Set Command target for the generated shell snippet: lint plus template, dry-run upgrade, or strict lint. The command is a starting point, so adjust chart path, release name, namespace, and values-file arguments for the real repository.
5. Use Error row limit when a noisy schema would create hundreds of rows. The issue ledger shows the rendered failures up to that limit and adds a truncation note when hidden errors remain.
6. Turn Require property descriptions and Warn on open objects on for maintainable chart schemas. Turn description warnings down only when validating an override against a chart you do not own.
7. Review Validation Report for pass/fail gates, Issue Ledger for exact fixes, Schema Coverage for declared paths, Severity Map Chart for triage, and Helm CI Snippet before copying commands into CI.

Interpreting Results:

Hard errors mean the values or schema cannot pass the selected review. Parsing errors stop meaningful validation. Schema failures mean a supplied value violates a declared rule, such as missing a required key, using the wrong type, choosing a value outside an enum, crossing a numeric boundary, or adding a key under a closed object.

Warnings usually point to chart quality rather than a direct values failure. Open objects can allow misspelled keys. Missing descriptions make the schema harder to review and maintain. Coverage warnings show values paths that are not represented clearly in root schema properties, which may indicate stale values, an intentional extension map, or a schema that should be tightened.

The false-confidence mistake is treating a passing schema as a passing deployment. Use the result to block malformed values early, then keep Helm rendering, Kubernetes validation, image checks, secrets review, and cluster-specific tests in the release process.

Technical Details:

The review has three inputs to reason about: the parsed YAML values object, the parsed JSON Schema object, and the selected profile. YAML must resolve to a mapping object for normal Helm chart configuration. The schema should also be a JSON object, usually with root type object and a properties block that describes top-level values keys.

Rule Core

Gate Logic

The main pass/fail decision is a rule gate rather than a numeric score. Parsing must succeed, the schema must compile, values must satisfy the schema, and no blocking errors can remain.

Warnings do not always close the gate, but profile selection changes how strongly hygiene findings should be treated. In override review, open-object and missing-description findings are informational because the user may not own the chart. In CI and schema-authoring profiles, those same findings are warnings because they can hide typo-prone values or weaken documentation.

Coverage Signal

Coverage is a structural signal, not a correctness proof. A high percentage means visible root values are represented by root schema properties, but the schema may still be too permissive if it uses broad types or open objects. A low percentage can mean the schema is incomplete, the values file contains stale keys, or the chart intentionally accepts arbitrary maps such as labels, annotations, or application settings.

For repeat checks, keep the same validation profile, command target, error row limit, description requirement, and open-object warning setting. Changing those choices can alter severity counts, coverage interpretation, and the generated CI command even when the pasted values and schema are unchanged.

Limitations and Privacy:

The pasted values and schema are checked in the browser session. The checker does not fetch chart repositories, merge multiple values files exactly like a full Helm command, render templates against Kubernetes capabilities, contact a cluster, run admission checks, or verify referenced images, secrets, storage classes, ingress classes, or CRDs.

• Redact production secrets, tokens, private registry names, customer identifiers, and internal hostnames before sharing exported reports or screenshots.
• Remote schema references are flagged because deterministic CI should not depend on network availability or external schema fetches.
• Schema validation checks configuration shape. It cannot prove that Kubernetes will accept the rendered manifests or that the workload will run successfully.

Advanced Tips:

• Use Helm CI gate with Warn on open objects enabled when schema drift should block or slow a release review.
• Use Override values review for third-party charts so maintainability warnings do not distract from actual values failures.
• Keep intentionally open maps narrow. Labels, annotations, and feature maps can stay flexible, while image, service, ingress, persistence, and resource objects usually benefit from closed properties.
• Treat a schema default as documentation. Put the value you want Helm to render in values.yaml or the override file.
• When the issue ledger is truncated, raise Error row limit only long enough to fix the repeated pattern, then return to a smaller limit for readable CI evidence.

Worked Examples:

These examples show how schema failures and hygiene warnings usually translate into chart-maintenance actions.

FAQ:

Glossary:

values.yaml

The default chart configuration file that users can override for a release.

values.schema.json

An optional chart-root JSON Schema file that declares the acceptable shape of the final Helm values object.

.Values

The merged values object available to chart templates during rendering.

additionalProperties

A JSON Schema keyword that controls whether object keys not listed in properties or matched by pattern rules are accepted.

Schema coverage

A comparison between supplied values keys and the schema properties that describe them.

Schema hygiene

Review signals such as descriptions, intentional open maps, and bundled references that make a schema easier to trust and maintain.

References:

• Helm Charts documentation
• Helm Values best practices
• JSON Schema object reference
• JSON Schema annotations reference