HIP-0027: Generate values.schema.json from values.yaml

hips/hip-0027.md

@@ -0,0 +1,116 @@
+---
+hip: 0027
+title: "Generate values.schema.json from values.yaml"
+authors: [ "@salvorusso" ]
+created: "2025-09-22"
+type: "feature"
+status: "draft"
+---
+
+## Abstract
+
+This proposal introduces a new Helm CLI subcommand to automatically generate a draft `values.schema.json` file from a chart’s `values.yaml`. The goal is to improve the developer experience for chart maintainers, lower the barrier for schema adoption, and encourage more consistent use of schema validation in Helm charts.
+
+## Motivation
+
+Helm supports validating values against a `values.schema.json`, but chart authors must currently write this file manually.
+While external tools exist (e.g., [helm-schema-gen](https://github.com/karuppiah7890/helm-schema-gen)), this functionality feels like a natural fit within Helm itself.
+
+Providing a first-class command inside Helm:
+
+* **Reduces friction**: Chart maintainers can bootstrap a schema instantly.
+* **Encourages adoption**: More charts will ship with `values.schema.json`.
+* **Unifies tooling**: Avoids reliance on third-party scripts for a common workflow.
+
+## Rationale
+
+The proposed feature is additive, has no impact on existing commands, and aligns with Helm’s mission of simplifying chart authoring. By starting with a basic generator that infers types and structures, Helm provides a helpful baseline while leaving fine-grained constraints (e.g., `required`, `enum`) to the chart author.
+
+## Specification
+
+### New Command
+
+```bash
+helm schema generate values.yaml [flags]
+```
+
+### Behavior
+
+* Parses `values.yaml`.
+* Infers JSON Schema types (`string`, `number`, `boolean`, `object`, `array`).
+* Outputs a draft schema to stdout or a file.
+* Optional: include YAML comments as `"description"`.
+
+### Example
+
+Input (`values.yaml`):
+
+```yaml
+replicaCount: 3
+image:
+  repository: nginx
+  tag: "1.25.0"
+  pullPolicy: IfNotPresent
+service:
+  enabled: true
+  type: ClusterIP
+  port: 80
+```
+
+Output (`values.schema.json`):
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "replicaCount": { "type": "integer" },
+    "image": {
+      "type": "object",
+      "properties": {
+        "repository": { "type": "string" },
+        "tag": { "type": "string" },
+        "pullPolicy": { "type": "string" }
+      }
+    },
+    "service": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "type": { "type": "string" },
+        "port": { "type": "integer" }
+      }
+    }
+  }
+}
+```
+
+## Backward Compatibility
+
+* No breaking changes.
+* Feature is optional and additive.
+
+## Security implications
+* No security impact.
+* Reads YAML and writes schema only; does not interact with cluster or secrets.
+
+## How to teach this
+* Update Helm documentation with examples.
+* Blog post announcing the feature.
+
+## Reference implementation
+
+N/A - to be developed if the proposal is accepted.
+
+## Rejected ideas
+
+## Open issues
+* Handling complex types (e.g., mixed arrays).
+* Deciding on defaults for ambiguous types.
+
+## References
+
+* [Helm values.schema.json docs](https://helm.sh/docs/topics/charts/#schema-files)
+* [helm-schema-gen](https://github.com/karuppiah7890/helm-schema-gen)
+* [JSON Schema draft-07](https://json-schema.org/draft-07/schema)
+* [HIP 1: Helm Improvement Proposal Process](https://github.com/helm/community/blob/main/hips/hip-0001.md)