[Enhancement] Also use values.schema.json

[danrspencer]

It's possible to provide a schema for a Helm chart via values.schema.json.

The schema specifies the structure of the chart along with types and descriptions of variables.

The type field would help with properties such as lists of objects, which the documentation generation currently doesn't have a good method of rendering.

The description field in the schema would be especially useful in large charts with areas of reuse as you would be able to enter a description once when specify a definition.

If there is a schema present then validating the values.yaml before process eliminates a large number of edge cases to worry about.

Assuming the values.yaml is valid then the docs should render the distinct list of fields from both values.schema.json and values.yaml.

If both a description in the schema is present along with a comment in the values.yaml then the comment should probably take precedence.

[estahn]

A JSON Schema should make it simpler to provide accurate documentation possibly removing the need for the custom syntax in the values file.

Maybe this can be an inspiration: https://github.com/adobe/jsonschema2md

[norwoodj]

Hey @danrspencer I think this is a very good idea. I've never written a values.schema.json file before. This is a new helm feature to me, in fact. So I hadn't thought to build this, but I appreciate the clear description of the feature, especially how conflicts and backwards-compatibility are handled.

I would merge this if implemented as you described. I do not have the time to do it myself at the moment, however.

[danrspencer]

I’m happy to have a go when I can find some time. I’ve never written Go but if you’re willing to field a few questions from me if I get stuck I’ll see what I can do.

[estahn]

I wonder how you would display #/definitions/... in Markdown. Would you still just generate the table or something more elaborate?

We do something like this:

{
  "type": "object",
  "$schema": "http://json-schema.org/schema#",
  "definitions": {
    "probe": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "initialDelaySeconds": {
          "type": "integer"
        },
        "periodSeconds": {
          "type": "integer"
        },
        "timeoutSeconds": {
          "type": "integer"
        },
        "httpGet": {
          "type": ["object", "null"]
        },
        "exec": {
          "type": "object"
        },
        "tcpSocket": {
          "type": ["object", "null"],
          "additionalProperties": true,
          "properties": {
            "port": {
              "type": ["string", "integer"]
            }
          }
        }
      }
    },
    "daemons": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "environment": {
          "type": "object"
        },
        "list": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "name": {
                "type": "string"
              },
              "args": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "command": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "resources": {
                "$ref": "#/definitions/resources"
              }
            }
          }
        },
        "secrets": {
          "type": "object"
        },
        "readinessProbe": {
          "$ref": "#/definitions/probe"
        },
        "livenessProbe": {
          "$ref": "#/definitions/probe"
        }
      }
    }
  }
}

Just wonder how that would be represented in Markdown in your mind.

[danrspencer]

I think definitions should just be treated as an internal implementation detail of the schema, so they’d be included before being rendered.

[remidebette]

Having this would be a great improvement

[stoetti]

Any plans on this enhancements?

[Nepo26]

I think that in the best case scenario, it would also allow the creation of the values.schema.json.

We could maybe import functionality from https://github.com/knechtionscoding/helm-schema-gen as it simply generates a schema.

[JuryA]

I think that in the best case scenario, it would also allow the creation of the values.schema.json.

However, it is imperative to carefully manage the directions. Exercise caution when dealing with, for example, the already existing values.schema.json. What I find particularly intriguing in the simpler scenario is providing the user with a switch, allowing them to specify the direction of synchronization - whether from values.yaml to values.schema.json, vice versa, or bidirectional synchronization. In the creation of values.schema.json, there may not be a substantial issue if it doesn't exist, but it's crucial to remember that the schema won't always remain simplistic. Through values.schema.json, it's possible (despite some challenges posed by an outdated JSON schema processing library, it's fully supported in most cases) to define multiple types for a single value or complex conditions. In this regard, exercising prudence is advisable.

Nonetheless, support for schemas is undoubtedly necessary; its absence is evident. During implementation, considering guidance like that provided at https://kubeapps.dev/docs/latest/howto/basic-form-support/ could be highly valuable, as compatibility with Kubeapps would be greatly appreciated. Additionally, values.schema.json should ideally be compatible with VSCode, following guidelines such as https://code.visualstudio.com/docs/languages/json#_use-rich-formatting-in-hovers and the entire documentation found at https://code.visualstudio.com/docs/languages/json. Underestimating this would be unwise, as robust support for these tools will surely be highly valued. Neglecting these nuances, on the other hand, would be a significant missed opportunity to address a longstanding gap in Helm's capabilities.

[Grraahaam]

Amazing tool! Thanks for this @norwoodj and all the contributors!

Just passing by to update this issue for people wanting to generate both README.md + values.schema.json, here's a tool that even support helm-docs's -- prefix : https://github.com/dadav/helm-schema

Here's how to integrate both annotations in a single values.yaml file, remember to put the @schema annotations before the helm-docs ones or you'll end up with a table containing the JSON schema data which isn't what we want

# @schema
# required: false
# @schema
# -- Override release name
nameOverride: ""

Hope it helps ✌️