Helm Values Schema Validator
Validate values.yaml against values.schema.json, with Helm-style failure details, schema coverage, hygiene warnings, and a CI command snippet.| Status | Area | Metric | Value | Evidence | Copy |
|---|---|---|---|---|---|
| {{ row.status }} | {{ row.area }} | {{ row.metric }} | {{ row.value }} | {{ row.evidence }} |
| Severity | Issue | Location | Evidence | Recommended action | Copy |
|---|---|---|---|---|---|
| {{ row.severity }} | {{ row.issue }} | {{ row.location }} | {{ row.evidence }} | {{ row.action }} |
| Schema path | Type | Required | Values status | Evidence | Copy |
|---|---|---|---|---|---|
| {{ row.path }} | {{ row.type }} | {{ row.required }} | {{ row.status }} | {{ row.evidence }} |
{{ ciSnippet }}Introduction:
Helm charts turn Kubernetes manifests into configurable release packages, and the values file is where most installation choices are made. A chart may expose image tags, replica counts, service ports, feature flags, resource limits, ingress settings, persistence options, and subchart switches through values.yaml. Those keys are convenient because operators can override them per environment, but they are also risky: one misspelled key, wrong type, or omitted required value can change the rendered manifests or fail a deployment late in a CI pipeline.
A values.schema.json file gives chart authors a formal contract for that configuration surface. Instead of relying only on README tables and template errors, the schema can state which values are required, which types are accepted, which strings must come from a known set, and which object shapes should reject unexpected keys. Helm applies that schema to the final values object used for rendering, so defaults, override files, and command-line settings need to be understood as one merged configuration rather than isolated snippets.
Schema validation is especially helpful when charts are shared across teams. Application developers often know the intended deployment knobs, platform teams know the cluster policies, and release automation needs deterministic failure messages. A clear schema sits between those groups: it documents the acceptable input shape, catches common mistakes before templates run, and makes breaking changes visible when chart values evolve.
The most useful schemas are strict where mistakes are expensive and flexible where chart consumers genuinely need extension points. additionalProperties: false can catch accidental keys, but it can also frustrate users if a chart intentionally passes through labels, annotations, or arbitrary application settings. Required properties make missing values obvious, but they should reflect true deployment requirements rather than author preference. Enumerations are valuable for fields such as service type or pull policy, while numeric ranges prevent invalid ports, replica counts, and timeout values from slipping through review.
Values schema validation does not prove that a release is safe to deploy. It does not contact the Kubernetes API server, evaluate cluster admission policies, confirm that an image exists, or guarantee that rendered manifests are semantically correct for a specific cluster. It is an early gate for configuration shape and chart hygiene. The best results come from pairing it with helm lint, template rendering, dry-run workflows, chart tests, and environment-specific review.
How to Use This Tool:
- Paste or load the
values.yamlcontent you want to check. Use chart defaults, a merged override file, or the values fragment that represents the deployment you are reviewing. - Paste or load the chart root
values.schema.json. The schema should describe the values object that Helm validates before rendering chart templates. - Choose the validation profile that matches the review: CI gate for release pipelines, schema authoring for maintainer checks, or override review for user-supplied values.
- Use the advanced options to set the generated Helm command style, cap noisy error tables, require property descriptions, and warn about open object shapes.
- Review the validation report, issue ledger, coverage summary, severity chart, and Helm command snippet before copying fixes back into the chart repository or CI job.
Interpreting Results:
The validation report separates hard schema failures from maintainability warnings. Hard failures mean the pasted values do not satisfy the schema: a required key may be missing, a value may have the wrong type, an enum value may be outside the allowed set, or a number may fall outside a declared range. These should usually block a release until either the values or the schema is corrected.
Hygiene warnings call out schema design choices that can weaken review. An open object warning means extra keys may pass through that part of the values tree. A missing description warning means the schema validates shape but does not help humans understand what a value controls. A coverage warning means a supplied values path is not represented clearly in the schema, which may indicate either an intentional extension point or a key that should be formalized.
The severity map is best read as a triage aid, not as a substitute for reading the issue ledger. A chart with one error can still be blocked if that error affects a required production field, while a chart with many warnings may be acceptable if those warnings are concentrated in intentionally free-form maps such as labels or annotations. Treat the generated CI snippet as a starting command set and adapt chart path, release name, namespace, Kubernetes version, and values files to the actual pipeline.
Technical Details:
Helm charts use YAML values as input to Go templates. Chart defaults live in values.yaml, and users can layer in additional values through files or command-line settings. Schema validation is applied to the effective values object, which matters because a key missing from the default file can still be supplied by an override, and a subchart restriction can still affect the parent release. In practical CI usage, the same schema gate can run during linting, rendering, installation, or upgrade workflows.
The schema language used by Helm relies on JSON Schema validation vocabulary. Common assertions include type, required, properties, additionalProperties, enum, minimum, maximum, pattern, items, and logical keywords such as allOf, anyOf, and oneOf. Annotation keywords such as description, title, and default can improve documentation and editor support, but validation should not depend on annotations changing the instance value.
Rule Core
| Rule family | Typical failure | Practical meaning |
|---|---|---|
| Parsing | Invalid YAML or JSON | The values or schema cannot be read reliably, so no meaningful contract check can run. |
| Type assertions | replicaCount: "3" when an integer is required |
The rendered template may receive a string where chart logic expects a number, object, list, or boolean. |
| Required properties | Missing image.repository or service.port |
The chart contract says the release cannot be rendered or reviewed without that value. |
| Enumerations and ranges | service.type: External or port 70000 |
The value is syntactically present but outside the allowed operational set. |
| Object strictness | Unexpected key under a closed object | The schema is catching a typo or an unsupported configuration path. |
| Schema hygiene | Undocumented property or open object | The contract validates less clearly than it could, even if the values currently pass. |
Coverage Signal
Coverage compares supplied values paths with schema paths. A high coverage signal means most visible configuration keys are represented by named schema properties or deliberate pattern rules. Low coverage can mean that the schema is incomplete, that the values file contains stale keys, or that the chart intentionally accepts free-form maps. Coverage is not the same as correctness: a schema can cover every path but still allow bad values if it uses overly broad types or permissive objects.
A useful review separates three questions:
- Does the instance pass? The supplied values satisfy the asserted schema constraints.
- Is the schema expressive enough? Important fields have types, ranges, enums, and closed objects where appropriate.
- Is the contract maintainable? Human-facing descriptions, intentional extension points, and CI commands make the schema practical to keep updated.
Gate Formula
The review status can be thought of as a gate over parse validity, schema validity, instance validity, and hygiene findings:
Warnings do not necessarily close the gate, but they identify places where a chart maintainer may want tighter constraints or clearer documentation before relying on the schema in automated releases.
Limitations and Privacy:
The checker validates pasted values and schema text in the browser session. It does not fetch a chart repository, merge multiple values files the way a full Helm command does, render templates against Kubernetes capabilities, execute admission checks, or confirm that referenced images, secrets, storage classes, ingress classes, or CRDs exist in a cluster.
Avoid pasting secrets from production values files. Even when a validation workflow is local, values files often contain credentials, tokens, private registry URLs, customer names, or internal hostnames. Redact sensitive fields before sharing screenshots, exported JSON, or issue ledgers in tickets.
Worked Examples:
Wrong Port Type
A values file sets service.port: "8080", while the schema requires an integer from 1 through 65535. The validation result should be treated as a blocking type error. Fix the values file to use 8080 as a number, or change the schema only if the chart templates intentionally accept a string and convert it later.
Unexpected Image Key
An image block includes image.repo, but the schema defines image.repository and closes the image object with additionalProperties: false. That is usually a useful typo catch. If the chart actually supports both names during migration, add an explicit compatibility rule rather than leaving the object open indefinitely.
Open Labels Map
A schema permits arbitrary entries under podLabels. The issue ledger may warn about an open object, but this can be acceptable because labels are commonly user-defined. The stronger pattern is to keep open maps narrow and intentional while closing higher-level chart settings where typos are more likely.
FAQ:
Does a passing schema mean the chart will install?
No. A passing schema means the supplied values match the declared configuration contract. Template rendering, Kubernetes API validation, permissions, CRDs, cluster policy, and runtime dependencies can still fail.
Should every object use additionalProperties: false?
No. Close objects where typos and unsupported keys are dangerous, such as image, service, resources, ingress, and persistence settings. Leave deliberate extension maps open when users need arbitrary labels, annotations, environment variables, or application-specific configuration.
Why check property descriptions?
Descriptions do not decide whether values pass validation, but they make schemas easier to review, generate documentation from, and maintain across chart versions. Missing descriptions are a maintainability signal rather than a Kubernetes error.
Can this replace helm lint?
No. Schema validation is one part of chart quality. Keep linting, template rendering, dry-run workflows, chart tests, and environment-specific checks in the release process.
Glossary:
values.yaml- The default chart configuration file that users can override for a release.
values.schema.json- An optional chart-root schema 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
propertiesare accepted. - Schema hygiene
- Review signals such as descriptions, intentional extension points, and coverage that make a schema easier to trust and maintain.