Four commands validate Helm values schema for engineers; use in CI

values.schema.json is an optional JSON Schema file that lives in a chart’s root directory. Helm uses it to validate the final, coalesced .Values object during helm install, helm upgrade, helm lint, and helm template. When it’s present, Helm checks types, catches missing required fields, and enforces constraints like enums and patterns before a release ever touches your cluster.

---

TL;DR:

• The schema file must be located at the top level of the chart directory and exactly named values.schema.json for Helm to detect and apply validation.
• Validation triggers during helm install, upgrade, lint, and template commands, automatically checking the merged values object without extra flags.
• Combining required fields with pattern constraints ensures that empty strings or invalid values are caught, preventing deployment failures caused by misconfigured values.
• Keep schemas simple and focus on critical fields, progressively tightening constraints through CI testing and updates based on production override patterns.
• Use validation tools and CI checks to catch schema violations early, but avoid using —skip-schema-validation except for specific network or external-reference issues.

---

Table of Contents

• What Is Values.schema.json and Where Does It Live in a Chart?
• When Does Helm Actually Run Schema Validation?
• How Do JSON Schema Types and Required Fields Work in Helm?
• Minimal Schema and Values.yaml Examples That Actually Validate
• What Are the Best Practices for Structuring Helm Values and Schemas?
• What Tools Help Generate and Validate Helm Value Schemas?
• How Do You Debug a Helm Values Schema Validation Error?
• A Practical Workflow for Building and Testing Value Schemas
• When Should You Actually Adopt Schema Validation for Your Charts?
• How Devopsaitoolkit Helps You Validate Helm Charts Before They Ship
• Sources
• FAQ

What Is Values.schema.json and Where Does It Live in a Chart?

Drop values.schema.json right next to values.yaml and Chart.yaml, at the chart’s root. That’s the only location Helm looks. There’s no configuration flag to point it elsewhere, no nested folder convention, no override. If the file isn’t sitting at the top level of the chart directory, Helm silently treats the chart as if it has no schema at all, which is often the first thing to check when validation you expected to run just doesn’t.

The filename matters too. It has to be exactly values.schema.json. Not schema.json, not values.json.schema, not values-schema.json. Helm’s chart loader looks for that exact string, and a typo means your carefully written schema gets ignored without so much as a warning.

Here’s what a typical chart directory looks like once you’ve added a schema:

• Chart.yaml (chart metadata)
• values.yaml (default values)
• values.schema.json (the schema that validates those values)
• templates/ (your Kubernetes manifests)
• charts/ (any subcharts, each of which can carry its own values.schema.json)

The file is genuinely optional. A chart without one behaves exactly the same at render time; templates still process, releases still install. What you lose is the safety net. Nobody catches a typo’d replicaCoun key or a string where an integer was expected until a pod fails to schedule or a container crashes on a bad config value.

Helm discovers and applies the schema automatically the moment it exists in that root directory. There’s no explicit --use-schema flag to opt in. If you want to opt out, that’s the flag you reach for, covered next. Under the hood, Helm loads the schema at the same point it merges values from values.yaml, parent chart overrides, -f files, and --set flags into the final .Values object it renders against, then validates that merged result rather than any single input file in isolation.

When Does Helm Actually Run Schema Validation?

Four commands trigger it: helm install, helm upgrade, helm lint, and helm template. Each one builds the coalesced values object and checks it against the schema before proceeding, and Helm’s own documentation confirms this happens automatically whenever values.schema.json is present, with no extra flag required to turn it on.

That makes helm lint and helm template the two commands worth wiring into continuous integration. Neither one requires a live cluster or a Tiller equivalent, so they’re cheap to run on every pull request:

• helm lint ./mychart catches schema violations, template syntax issues, and missing required values.
• helm template ./mychart -f custom-values.yaml renders manifests locally and validates the exact values a real deployment would use.
• Both fail with a non-zero exit code on schema violations, which is what makes them useful as CI gates rather than just local sanity checks.

Sometimes you need to bypass validation entirely. The --skip-schema-validation flag does exactly that, and it exists for real operational reasons, not just as an escape hatch for lazy debugging. Air-gapped environments are the classic case: if your schema uses a remote $ref pointing to an external URL and that network call can’t resolve, validation fails hard even when your values are perfectly fine. Helm’s upgrade documentation lists this flag specifically for scenarios like that.

Statistic Callout: Validation isn’t limited to the top-level chart. It recurses through every subchart in the dependency tree, checking each subchart’s own schema against the relevant slice of the coalesced values. A parent chart cannot override its way around a subchart’s required field. If the subchart says a key is mandatory, the parent has to supply it, as Helm’s charts documentation states directly.

Use --skip-schema-validation sparingly. It’s a valid tool for a specific network problem, not a general workaround for a schema you haven’t finished writing yet.

How Do JSON Schema Types and Required Fields Work in Helm?

Every values.schema.json file starts the same way most JSON Schema documents do: with a $schema key declaring the draft version, followed by type: object at the root, since .Values is always an object. From there, you define properties, each one describing a key in your values file.

The keywords that do the real work are type, properties, required, enum, pattern, minimum/maximum, and items. JSON Schema’s own reference documentation covers these in detail, and they map cleanly onto YAML structures:

• type restricts a field to string, integer, boolean, object, or array.
• required lists which properties must be present in the object.
• enum limits a string or number to a fixed set of allowed values.
• pattern applies a regular expression to string fields.
• minimum/maximum bound numeric fields.
• items defines the schema for entries inside an array.

Here’s the nuance that trips up almost everyone the first time they write a schema: required only checks that a key exists in the object. It says nothing about whether that key has a meaningful value. A YAML entry like image: "" or even image: with nothing after the colon technically satisfies required while leaving you with an empty string Helm will happily inject into a template. The field author must combine required with a pattern that explicitly excludes empty strings to actually enforce non-empty input, a distinction several practical Helm schema tutorials call out because it’s so easy to miss.

Pro Tip: Test that assumption yourself before trusting it. Set a field to an empty string, run helm template against your chart, and watch whether validation actually catches it. If it doesn’t, your required list is giving you a false sense of coverage.

There’s a second layer of complexity around merging. When Helm coalesces values from values.yaml, -f override files, and --set flags, arrays generally replace rather than merge, while objects merge key by key. That matters for schema design: if a user overrides an array field with --set, your schema needs to validate the entire replacement array, not just the original default. Object properties, on the other hand, merge recursively, so partial overrides of nested objects still need every required sibling key to be present somewhere in the merge chain.

Minimal Schema and Values.yaml Examples That Actually Validate

A working example beats an abstract explanation. Here’s a minimal values.schema.json for a chart that deploys a single container:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image", "replicaCount"],
  "properties": {
    "image": {
      "type": "object",
      "required": ["repository", "tag", "pullPolicy"],
      "properties": {
        "repository": {
          "type": "string",
          "pattern": "^[^\\s]+$"
        },
        "tag": {
          "type": "string",
          "pattern": "^[^\\s]+$"
        },
        "pullPolicy": {
          "type": "string",
          "enum": ["Always", "IfNotPresent", "Never"]
        }
      }
    },
    "replicaCount": {
      "type": "integer",
      "minimum": 1
    }
  }
}

And the matching values.yaml:

image:
  repository: nginx
  tag: "1.27"
  pullPolicy: IfNotPresent
replicaCount: 2

The pattern on repository and tag (^[^\s]+$) enforces at least one non-whitespace character, which is exactly the technique that closes the empty-string gap required leaves open. The enum on pullPolicy means someone typing pullpolicy: always in lowercase, or misspelling IfNotPresnt, gets caught before the pod spec ever renders.

Constraint goal	Schema keyword combination	What it catches
Non-empty string	type: string + pattern: ^[^\s]+$	Empty or whitespace-only values that required alone misses
Constrained set of options	type: string + enum: [...]	Typos or invalid values like a misspelled pull policy
Positive integer	type: integer + minimum: 1	Zero or negative replica counts
Nested object requirement	required inside a nested properties block	Missing keys inside image, resources, or similar objects

Run helm template ./mychart --set image.tag="" against that schema and validation fails immediately, pointing at the tag property. That’s the coalesced-values behavior in action: Helm doesn’t validate your static values.yaml file, it validates whatever comes out the other side after --set and -f overrides are merged in.

What Are the Best Practices for Structuring Helm Values and Schemas?

1. Keep values.yaml flat wherever possible. Deeply nested structures look tidy but make --set overrides painful to write and easy to get wrong. Helm’s own best practices guidance recommends favoring shallow structures specifically because they keep override syntax simple.
2. Document every property, and start each comment with the property name. A doc string like # replicaCount -- number of pod replicas is grep-friendly and plays nicely with schema generators that scrape comments to build documentation automatically.
3. Validate the fields that actually cause incidents first. Don’t try to schema-lock every possible key on day one. Image references, resource limits, and required secrets are the fields that break production when they’re wrong; start there and expand coverage as real gaps surface.
4. Test against the coalesced object, not just the defaults. Run your schema against combinations of parent overrides, -f files, and subchart values, because that’s the actual object Helm validates in production, not the pristine values.yaml you wrote in isolation.

Pro Tip: If you’re migrating an existing chart to schema validation, don’t roll out a strict schema on a Friday afternoon. Start with a permissive schema that only checks types, ship it, watch CI for a week, then tighten required lists and add enum/pattern constraints incrementally.

What Tools Help Generate and Validate Helm Value Schemas?

Writing a schema by hand from scratch is tedious and error prone. Most teams start by inferring a rough schema from an existing values.yaml, then hand tightening the patterns and enums that matter. That two-pass approach, generate first, refine second, tends to produce a far more usable schema than trying to write every constraint perfectly on the first attempt.

Community tooling makes the first pass faster. The helm-schema project on GitHub generates values.schema.json from annotated values files or inline comments, giving you a working baseline instead of a blank file. It’s a reasonable starting point for charts that don’t have a schema yet, though it’s worth reviewing the output rather than committing it blind, since generated patterns tend to be looser than what you’d write by hand for security-sensitive fields.

Editor integration pays off almost immediately. Associating values.schema.json with your values.yaml file in VS Code (via the YAML extension’s schema mapping) gives you autocompletion and inline red squiggles the moment a value violates the schema, catching mistakes before you even run helm lint.

CI is where schema validation earns its keep long term:

• Add helm lint ./chart as a required PR check so schema violations fail the build, not the deployment.
• Run helm template ./chart -f values-staging.yaml against every environment’s override file to catch environment-specific violations before merge.
• Fail the pipeline on non-zero exit codes from either command; don’t just log warnings and move on.

If you’re using AI tools to draft a schema, treat the output as a seed, not a finished product. AI-assisted generation can produce a reasonable first draft of types and structure quickly, but tightening patterns, enums, and the required-versus-empty-string distinction still needs a human who understands what the chart actually deploys.

How Do You Debug a Helm Values Schema Validation Error?

1. Read the error path literally. Helm’s validation errors point to the exact key in the coalesced object that failed, something like image.tag: Does not match pattern. Map that path back to the values file or --set flag that set it.
2. Reproduce locally before fixing anything. Run helm template ./chart -f values.yaml --set image.tag="" to rebuild the exact coalesced object CI saw. This isolates whether the bug is in your values or your schema.
3. Check for the empty-string gap first. If a required field is technically present but validation still fails downstream, or worse, doesn’t fail when it should, you’re probably missing a pattern constraint on that field.
4. Fix remote $ref failures by vendoring. If your schema references an external URL and CI runs in a restricted network, copy the referenced schema into your repo instead of relying on a live fetch every build.
5. Relax, don’t delete, mismatched subchart requirements. If a subchart update adds a new required field your parent chart doesn’t set, add a sensible default rather than stripping the requirement out of the subchart’s schema; that requirement exists for a reason someone else set.

Pro Tip: Keep a scratch values file with intentionally broken values (empty strings, wrong types, invalid enums) in your test directory. Running your schema against known-bad input regularly is the fastest way to catch a schema that’s gone soft over time.

For deployment errors that trace back further than the schema itself, common Helm chart deployment error patterns are worth a separate look.

A Practical Workflow for Building and Testing Value Schemas

The workflow that holds up under real production pressure is simple: infer, tighten, add to the chart, validate in CI. Start with a generated or hand-drafted schema covering basic types. Tighten it with patterns and enums for the fields that matter most, usually image references, resource limits, and anything security sensitive. Commit values.schema.json alongside the chart. Then wire helm lint and helm template into CI so every pull request proves the schema still holds against real override combinations.

A few habits make this workflow durable rather than a one-time exercise:

• Run schema validation against staging and production override files, not just the chart’s own defaults.
• Revisit the schema whenever a subchart dependency bumps its version, since subchart requirement changes recurse into your validation.
• Keep a written record of why each pattern or enum exists; a schema with unexplained constraints gets loosened by the next engineer who hits it and doesn’t understand the reasoning.
• Before merging a schema change, run it against chart testing practices that already cover your chart to catch interaction effects with existing test fixtures.

Teams that generate charts or review them with AI-assisted tools should treat AI-generated Helm content the same way as any other draft: useful for a fast first pass, but not something to commit to main without a human checking the pattern constraints against what the chart is actually meant to enforce.

When Should You Actually Adopt Schema Validation for Your Charts?

Schema validation earns its cost the moment a chart’s values file gets shared across more than one team, or the chart ships outside your own organization. Before that point, a values.schema.json can feel like ceremony for a config only two people ever touch.

The mistake I see most often is teams trying to schema-lock everything on the first pass, which just produces a brittle schema everyone routes around with --skip-schema-validation. Start loose. Validate types and the handful of fields that have actually caused incidents. Expand coverage once real override patterns show up in production logs and pull requests, not before.

CI gates matter more than schema completeness. A thin schema enforced consistently in every pull request beats an exhaustive schema nobody runs until deploy day.

— James

How Devopsaitoolkit Helps You Validate Helm Charts Before They Ship

Writing a correct schema on paper is one thing. Knowing whether your chart’s coalesced values, including every subchart override your team actually uses in production, pass that schema cleanly is another. Devopsaitoolkit is built for engineers who need that answer fast, without waiting on a review cycle to catch a broken required list after it’s already in staging.

The Kubernetes Health Check runs $300 one-off and covers exactly this kind of gap: a hands-on review of your charts, values structure, and CI validation gates, with concrete remediation steps rather than a generic report. If your team is publishing charts externally or sharing values files across services, that’s the point where a second set of eyes on schema coverage pays for itself the first time it catches a bad override before a production rollout does. For ongoing prompt libraries and validators covering the rest of your Kubernetes and infrastructure stack, see the pricing page for current plan details. Book a health check or browse the toolkit to see where your chart’s schema coverage actually stands.

Sources

• Charts (Helm docs)
• JSON Schema - type (understanding JSON Schema)

FAQ

How Do I See a Helm Chart’s Values?

Run helm show values <chart> to see a chart’s default values.yaml before installing it, or helm get values <release> to see the values currently applied to a running release. Add --all to helm get values to see the full coalesced set, including defaults not explicitly overridden.

Is Helm Deprecated?

No. Helm remains the standard package manager for Kubernetes and is actively maintained, with regular releases and ongoing documentation updates covering features like schema validation. It’s under active development, not deprecated.

Does YAML Have a Schema?

YAML itself has no built-in schema language, which is exactly why Helm uses JSON Schema instead, applied through values.schema.json, to validate YAML values files. The schema treats the parsed YAML as a JSON-like object and checks it against standard JSON Schema keywords such as type, required, and enum.

Can You Explain What a Helm Chart Is in Simple Terms?

A Helm chart is a packaged bundle of Kubernetes manifest templates, default configuration values, and metadata that together define a deployable application. You customize a chart’s behavior by editing values.yaml or passing --set flags, and Helm renders those values into finished Kubernetes YAML at install time.

What Happens if a Chart Has No Values.schema.json File?

Nothing breaks. Helm renders and installs the chart exactly as it would with a schema present, it simply skips validation entirely since there’s nothing to check against. The tradeoff is that typos, wrong types, and missing fields surface later, often as a pod failure or misconfigured deployment instead of an upfront error.

Recommended

• Testing Helm Charts Before They Reach Production
• Generating values.schema.json for Helm Charts With AI
• Automating Helm Chart Deployments: A DevOps Guide
• Common Helm Chart Deployment Errors: Fix Them Fast