Helm, JSON Schema, and Generated Forms

One of the really powerful new features in Helm v3 is the use of JSON Schemas. This is great for validation, documentation, and it can be used for automated form generation. We’ll take a quick look at what they are, how you can generate them (i.e. you don’t need to write the whole thing by hand), and how they can be used to generate web forms.

JSON Schema

The basics… when you have a JSON Schema file in your chart (it’s optional), alongside the values.yaml file, Helm will validate the values used to render the chart against this schema file. This is a way to validate all or part of the values are in the right format. This can catch structure problems, type problems, and more.

Technically, JSON Schemas are based on XML schemas and they provide a way to annotate and validate JSON files. XML schemas may seen difficult to create or bothersome. They don’t have to be. In a moment we’ll take a look at an easy way to generate them.

JSON Schemas can be used on YAML files due to the way you can transform between JSON and YAML files. One is a super set of the other and transforms are possible.

The following is an example of part of a JSON Schema file. Helm looks for a file named values.schema.json.

{
    "$schema": "http://json-schema.org/schema#",
    "type": "object",
    "properties": {
        "affinity": {
            "type": "object"
        },
        "fullnameOverride": {
            "type": "string"
        },
        "image": {
            "type": "object",
            "properties": {
                "pullPolicy": {
                    "type": "string"
                },
                "repository": {
                    "type": "string"
                },
                "tag": {
                    "type": "string"
                }
            }
        },
...

You can read more about the structure in the docs.

Automated Generation

Writing a JSON Schema file by hand can be time consuming. Luckily, there is a Helm plugin that can help.

Once you have the plugin installed you can run a command like:

$ helm schema-gen values.yaml > values.schema.json

The plugin reads the passed in values.yaml file, generates a schema, and sends it to output (i.e. standard out). You can read this or send it to a file.

The generated file only contains basic information. It’s a good starting point. There is other information that can and maybe should be added to the schema. For example, you can add a description like the following:

"hosts": {
    "type": "array",
    "description": "A list of host names",
    "items": {
        "type": "object",
...

This description can be used to tell people what the values are. More on how this is useful in a minute.

Validation is another important element. In Helm values you’ll find yourself passing around a lot of strings. JSON Schemas enable you to have more specific validation on strings such as specific formats (e.g., email addresses), length, and more. You can even use regular expressions. More information on this is in the docs.