How does a chart's values.schema.json keep three per-environment values files to one shape?

## What the file is `values.schema.json` is an optional JSON Schema document in the chart's root directory, beside `Chart.yaml` and `values.yaml`. When it is present, Helm validates the values against it and refuses to proceed if they do not conform, naming the chart and the offending path. Validation runs on `helm install`, `helm upgrade`, `helm template` and `helm lint`, which is what makes it useful as a promotion guard: the same check that would stop a bad production deploy can be run in a pull request with no cluster in sight. ## The one fact people get wrong The schema is applied to the **merged** values, after chart defaults, every `-f` file and every `--set` have been combined — not to each file in isolation. Two consequences follow. First, `required` does not mean 'the environment file must set this'. If `values.yaml` supplies a default for the key, the merged document always has it and the requirement is always satisfied. `required` only bites for keys the chart deliberately leaves unset, which is exactly how you force every environment to declare, say, its ingress hostname rather than silently inheriting someone else's. Second, validating the environment you happen to be deploying tells you nothing about the other two. Holding three files to one shape is a CI job, not a property of the file: ```bash for env in dev staging prod; do helm lint charts/fraud-platform -f "values/${env}.yaml" done ``` ## The constraints that actually catch drift **Types.** YAML makes `replicaCount: "11"` a string, and a template that does arithmetic on it fails in a way whose error points at the template, not at the file. `"type": "integer"` fails at the front door instead. **Enums and patterns.** `logLevel` constrained to `debug|info|warn|error` stops a production file acquiring `verbose` because the application once accepted it. A `pattern` on an image tag can stop `latest` reaching production. **Bounds.** `"minimum": 2` on a production replica count encodes an operational rule in a place the deploy cannot bypass. **`additionalProperties: false`.** This is the strongest anti-drift constraint and the least used. Without it, a misspelled key in an environment file is not an error at all — Helm merges `replicacount: 11` into the values, no template reads it, and the environment quietly runs the default. With it, the typo fails the render. The catch on an umbrella chart is that a subchart's values live under the subchart's name in the parent's values, so setting `additionalProperties: false` at the parent root will reject the `api:` and `worker:` blocks unless the parent schema declares those properties. Declare them, even loosely as objects, and let each subchart's own `values.schema.json` police its interior. Because validation happens after merging, the same constraints also catch a mistyped `--set` key supplied by a deploy job, not just a mistake in a committed file. That is the one place where a schema protects you from an argument nobody reviewed: a job that passes `--set api.replicaCont=11` fails the upgrade instead of quietly deploying the default replica count into production. ## What it cannot do A schema constrains **shape**, never **meaning**. It will happily accept a production file whose hostname still points at staging's fraud-scoring endpoint, whose queue name is the one dev uses, or whose replica count is right for a load test and wrong for Friday afternoon. Those are review problems and smoke-test problems. The schema also cannot tell you that a key present in production is absent from staging — unless you have made it required, in which case the staging render fails and you find out on the pull request. For anything the schema cannot express, the `required` template function is the runtime backstop: `{{ required "api.ingress.host must be set" .Values.api.ingress.host }}` fails the render with a message aimed at the person who forgot, rather than producing an Ingress with an empty host. ## Where it fits in promotion Treat the schema as the contract the environment files are all instances of. It is written once, in the chart, and it is the reason a new environment can be created by copying the schema's requirements rather than copying production's file and deleting the frightening parts. Combined with rendering every environment on every change, it converts 'the prod values file drifted' from an incident into a failed check.