helm values schema json plugin

Helm plugin for generating values.schema.json from single or multiple values files. Schema can be enriched by reading annotations from comments. Works only with Helm3 charts.

Installation

helm plugin install https://github.com/losisin/helm-values-schema-json.git

Upgrading

helm plugin update schema

See changelogs:

• Breaking changes
• Full release notes in GitHub Releases

Features

• Add multiple values files and merge them together - default is values.yaml in the current working directory
• Save output with custom name and location - default is values.schema.json in current working directory
• Use preferred schema draft version - default is draft 2020
• Read annotations from comments.
• Read description from helm-docs
• Bundling subschemas referenced in $ref

See docs for more info or checkout example yaml files in testdata.

Integrations

There are several ways to automate schema generation with this plugin. Main reason is that the json schema file can be hard to follow and we as humans tend to forget and update routine tasks. So why not automate it?

GitHub actions

There is GitHub action that I've build using typescript and published on marketplace. You can find it here. Basic usage is as follows:

name: Generate values schema json
on:
  - pull_request
jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
      with:
        ref: ${{ github.event.pull_request.head.ref }}
      - name: Generate values schema json
        uses: losisin/helm-values-schema-json-action@v1
        with:
          input: values.yaml

pre-commit hook

With pre-commit, you can ensure your JSON schema is kept up-to-date each time you make a commit.

First install pre-commit and then create or update a .pre-commit-config.yaml in the root of your Git repo with at least the following content:

repos:
  - repo: https://github.com/losisin/helm-values-schema-json
    rev: v1.7.2
    hooks:
      - id: helm-schema
        args: ["--values", "values.yaml"]

Then run:

pre-commit install
pre-commit install-hooks

Further changes to your chart files will cause an update to json schema when you make a commit.

Husky

This is a great tool for adding git hooks to your project. You can find it's documentation here. Here is how you can use it:

"husky": {
  "hooks": {
    "pre-commit": "helm schema --values values.yaml"
  }
},

CI/CD fail-on-diff

You can use this plugin in your CI/CD pipeline to ensure that the schema is always up-to-date. Here is an example for GitLab #82:

schema-check:
  script:
    - cd path/to/helm/chart
    - helm schema -output generated-schema.json
    - CURRENT_SCHEMA=$(cat values.schema.json)
    - GENERATED_SCHEMA=$(cat generated-schema.json)
    - |
      if [ "$CURRENT_SCHEMA" != "$GENERATED_SCHEMA" ]; then
        echo "Schema must be re-generated! Run 'helm schema' in the helm-chart directory" 1>&2
        exit 1
      fi

Usage

$ helm schema --help
Usage:
  helm schema [flags]

Flags:
      --bundle                              Bundle referenced ($ref) subschemas into a single file inside $defs
      --bundle-cache-min string             Minimum cache duration for downloaded schemas, e.g. 24h or 30m. Raises short server Cache-Control max-age values; empty follows the server
      --bundle-root string                  Root directory to allow local referenced files to be loaded from (default current working directory)
      --bundle-without-id                   Bundle without using $id to reference bundled schemas, which improves compatibility with e.g the VS Code JSON extension
      --config string                       Config file for setting defaults. (default ".schema.yaml")
      --draft int                           Draft version (4, 6, 7, 2019, or 2020) (default 2020)
  -h, --help                                help for helm schema
      --indent int                          Indentation spaces (even number) (default 4)
      --k8s-schema-url string               URL template used in $ref: $k8s/... alias (default "https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/{{ .K8sSchemaVersion }}/")
      --k8s-schema-version string           Version used in the --k8s-schema-url template for $ref: $k8s/... alias
      --no-additional-properties            Default additionalProperties to false for all objects in the schema, or unevaluatedProperties where properties also come from a $ref or allOf
      --no-default-global                   Disable automatic injection of 'global' property when schema root does not allow it
  -o, --output string                       Output file path (default "values.schema.json")
      --schema-root.additional-properties   Allow additional properties
      --schema-root.description string      JSON schema description
      --schema-root.id string               JSON schema ID
      --schema-root.ref string              JSON schema URI reference. Relative to current working directory when using "-bundle true".
      --schema-root.title string            JSON schema title
      --use-helm-docs                       Read description from https://github.com/norwoodj/helm-docs comments
  -f, --values strings                      One or more YAML files as inputs. Use comma-separated list or supply flag multiple times (default [values.yaml])
  -v, --version                             version for helm schema

Lint subcommand

Use helm schema lint to validate your config file and its input values files without generating a schema. It parses the input files using the same parsing as schema generation and reports any errors, and warns about unknown fields in the config file (.schema.yaml):

$ helm schema lint
No issues found

Pass --strict to exit with a non-zero code when any warning is reported, which is useful in CI:

$ helm schema lint --strict
warning: line 4: field fooBar is not a known config field
Found 1 warning(s)
Error: found 1 warning(s) in strict mode

$ helm schema lint --help
Usage:
  helm schema lint [flags]

Flags:
  -h, --help     help for lint
      --strict   Fail with a non-zero exit code when any warning is reported

Global Flags:
      --config string   Config file for setting defaults. (default ".schema.yaml")

Bundle subcommand

Use helm schema bundle to run only the bundler on an existing JSON schema file and print the bundled result to stdout, without generating a new schema from values files:

$ helm schema bundle values.schema.json
{
  ...
}

This resolves every $ref in the file, stores the referenced subschemas inside $defs, and prints the bundled schema. It is the same bundling that helm schema --bundle performs while generating a schema, but applied to an already-existing schema file.

$ helm schema bundle --help
Usage:
  helm schema bundle SCHEMA_FILE [flags]

Flags:
      --bundle-cache-min string     Minimum cache duration for downloaded schemas, e.g. 24h or 30m. Raises short server Cache-Control max-age values; empty follows the server
      --bundle-root string          Root directory to allow local referenced files to be loaded from (default current working directory)
      --bundle-without-id           Bundle without using $id to reference bundled schemas, which improves compatibility with e.g the VS Code JSON extension
  -h, --help                        help for bundle
      --indent int                  Indentation spaces (even number) (default 4)
      --k8s-schema-url string       URL template used in $ref: $k8s/... alias (default "https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/{{ .K8sSchemaVersion }}/")
      --k8s-schema-version string   Version used in the --k8s-schema-url template for $ref: $k8s/... alias

Global Flags:
      --config string   Config file for setting defaults. (default ".schema.yaml")

Note

The bundle command does not load settings from .schema.yaml (or --config). It applies only the flags shown above. Config-file fields such as bundleRoot, indent, and k8sSchemaVersion are ignored when bundling an existing schema file — pass the corresponding --bundle-root, --indent, and --k8s-schema-version flags directly instead. The --config flag is inherited from the root command but has no effect on bundle.

Configuration file

Uses .schema.yaml in the current working directory. Example:

# .schema.yaml
# yaml-language-server: $schema=https://github.com/losisin/helm-values-schema-json/raw/refs/heads/main/config.schema.json

values:
  - values.yaml

draft: 2020
indent: 4
output: values.schema.json

bundle: false
bundleRoot: ""
bundleWithoutID: false
bundleCacheMin: ""

k8sSchemaURL: https://raw.githubusercontent.com/yannh/kubernetes-json-schema/refs/heads/master/{{ .K8sSchemaVersion }}/
k8sSchemaVersion: "v1.33.1"

useHelmDocs: false

noAdditionalProperties: false
noDefaultGlobal: false

schemaRoot:
  id: https://example.com/schema
  title: Helm Values Schema
  description: Schema for Helm values
  additionalProperties: true

All options available from CLI can be set in this file. However, do note that the file uses camelCase, while the flags uses kebab-case.

Then, just run the plugin without any arguments:

helm schema

You can override which config file to use with the --config flag:

helm schema --config ./my-helm-schema-config.yaml

CLI

Basic

In most cases you will want to run the plugin with default options:

$ helm schema

This will read values.yaml, set draft version to 2020-12 and save output to values.schema.json.

Extended

Multiple values files

Merge multiple values files, set json-schema draft version explicitly and save output to my.schema.json:

values_1.yaml

nodeSelector:
  kubernetes.io/hostname: ""
dummyList:
  - "a"
  - "b"
  - "c"
key1: "asd"
key2: 42
key3: {}
key4: []

custom/path/values_2.yaml

nodeSelector:
  kubernetes.io/hostname: "node1"
deep:
  deep1:
    deep2:
      deep3:
        deep4: "asdf"

Run the following command to merge the yaml files and output json schema:

helm schema --values values_1.yaml,custom/path/values_2.yaml --draft 7 --output my.schema.json

Output will be something like this:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "deep": {
            "type": "object",
            "properties": {
                "deep1": {
                    "type": "object",
                    "properties": {
                        "deep2": {
                            "type": "object",
                            "properties": {
                                "deep3": {
                                    "type": "object",
                                    "properties": {
                                        "deep4": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "dummyList": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "key1": {
            "type": "string"
        },
        "key2": {
            "type": "integer"
        },
        "key3": {
            "type": "object"
        },
        "key4": {
            "type": "array"
        },
        "nodeSelector": {
            "type": "object",
            "properties": {
                "kubernetes.io/hostname": {
                    "type": "string"
                }
            }
        }
    }
}

Note

When using multiple values files as input, the plugin follows Helm's behavior. This means that if the same yaml keys are present in multiple files, the latter file will take precedence over the former. The same applies to annotations in comments. Therefore, the order of the input files is important.

Root JSON object properties

Adding ID, title and description to the schema:

basic.yaml

image:
  repository: nginx
  tag: latest
  pullPolicy: Always

helm schema --values values.yaml --schema-root.id "https://example.com/schema" --schema-root.ref "schema/product.json" -schema-root.title "My schema" --schema-root.description "This is my schema"

Generated schema will be:

{
    "$id": "https://example.com/schema",
    "$ref": "schema/product.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": true,
    "description": "This is my schema",
    "properties": {
        "image": {
            "properties": {
                "pullPolicy": {
                    "type": "string"
                },
                "repository": {
                    "type": "string"
                },
                "tag": {
                    "type": "string"
                }
            },
            "type": "object"
        }
    },
    "title": "My schema",
    "type": "object"
}

Issues, Features, Feedback

Your input matters. Feel free to open issues for bugs, feature requests, or any feedback you may have. Check if a similar issue exists before creating a new one, and please use clear titles and explanations to help understand your point better. Your thoughts help me improve this project!

How to Contribute

🌟 Thank you for considering contributing to my project! Your efforts are incredibly valuable. To get started:

1. Fork the repository.
2. Create your feature branch: git checkout -b feature/YourFeature
3. Commit your changes: git commit -am 'Add: YourFeature'
4. Push to the branch: git push origin feature/YourFeature
5. Submit a pull request! 🚀