helm-values-schema-json

repository·main·Indexed 42 days ago

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

A Helm plugin for Helm3 charts that generates JSON schemas (values.schema.json) from Helm values files. It allows developers to define types, validation keywords, and metadata using @schema annotations in YAML comments. Features include support for merging multiple files, bundling referenced schemas, Kubernetes schema aliases via $k8s, and integration with helm-docs for descriptions.

Tokens: 8.3K
Snippets: 38
Records: 45
Agent score: 43%

What's inside helm-values-schema-json

Configure types and nullability
main
You can restrict values to specific primitive types or allow them to be null using the @schema annotation.
Type
Supported types include: string, number, integer, boolean, object, array, and null.
Multiple Types
To allow a value to be one of several types (e.g., for keys without declared values), use the syntax type:[type1, type2]. This results in a JSON schema type array.
Nullable
The nullable keyword is a shorthand that appends null to the type inferred from the YAML value. It is semantically equivalent to explicitly listing null in a type array.
Example equivalence:
- replicaCount: # @schema type:[integer, null]
- replicaCount: # @schema type: integer; nullable
```
# Explicit multiple types
replicaCount: # @schema type:[integer, null]

# Using nullable shorthand
nameOverride: "" # @schema nullable

# Using type with nullable
replicaCount: # @schema type: integer; nullable
```
https://github.com/losisin/helm-values-schema-json/blob/main/docs/README.md
How to use annotations from comments
main
The helm-values-schema-json tool allows you to generate JSON schemas by adding annotations directly to your YAML files using comments.
To avoid interference with other tools like helm-docs, all annotations must start with the prefix # @schema.
Placement Options
Annotations can be placed in three ways:
1. On the same line as the property.
2. Directly above the property.
3. Directly below the property (ensure indentation matches the property it describes).
Multiple Annotations
You can add multiple annotations to a single line by separating them with a semicolon (;).
Note: Support for comments above and below a property was introduced in v2.0.0. Versions prior to v2.0.0 only support end-of-line comments.
```
# On the same line
fullnameOverride: "myapp" # @schema maxLength:10;pattern:^[a-z]+$

# On the line above
# @schema maxLength:10;pattern:^[a-z]+$
nameOverride: "myapp"

# On the line below
resources:
  limits: {}
  requests: {}
# @schema additionalProperties:false
```
https://github.com/losisin/helm-values-schema-json/blob/main/docs/README.md
Use boolean flags in helm schema v2.0
main
Boolean flags in v2.0 no longer require an explicit true or false value. Specifying the flag name implicitly sets it to true. To set a boolean flag to false, you must use the equals sign syntax (--flag=false).
```
# Setting to true
- helm schema -bundle true
+ helm schema --bundle
+ helm schema --bundle=true

# Setting to false
- helm schema -bundle false
+ helm schema --bundle=false
```
https://github.com/losisin/helm-values-schema-json/blob/main/docs/upgrading/v1.9-to-v2.0.md
Use Schema Composition (allOf, anyOf, oneOf, not)
main
You can use logical composition keywords to create complex validation rules. When using these keywords, the type field is dropped from the immediate level and must be declared within the subschema provided for the keyword.
- allOf: Requires the value to match all provided schemas. digest: sha256:1234567890 # @schema allOf: [{type: string}, {minLength: 14}]
- anyOf: Requires the value to match at least one of the provided schemas. nodes: 3 # @schema anyOf: [{type: number, multipleOf: 3}, {type: number, multipleOf: 5}]
- oneOf: Requires the value to match exactly one of the provided schemas. version: # @schema oneOf: [{type: string}, {type: number}]
- not: Requires the value to NOT match the provided schema. tag: latest # @schema not: {type: object}
```
image:
  digest: sha256:1234567890 # @schema allOf: [{type: string}, {minLength: 14}]

cluster:
  nodes: 3 # @schema anyOf: [{type: number, multipleOf: 3}, {type: number, multipleOf: 5}]

MY_SECRET:
  version: # @schema oneOf: [{type: string}, {type: number}]

image:
  tag: latest # @schema not: {type: object}
```
https://github.com/losisin/helm-values-schema-json/blob/main/docs/README.md
Automatic injection of Helm 'global' values in v2.3.0+
main
In version 2.3.0 and later, helm schema automatically injects a global property into the JSON schema to support Helm dependencies. This injection occurs only if all of the following conditions are met:
1. /properties/global is not already set.
2. /additionalProperties is not null or unset.
3. /additionalProperties is not true.
4. /additionalProperties/type is not null or unset.
5. /additionalProperties/type does not contain object.
The injected property looks like this:
```
"global": {
    "description": "Global values shared between all subcharts",
    "$comment": "Added automatically by 'helm schema' to allow this chart to be used as a Helm dependency, as the `additionalProperties` setting would otherwise collide with Helm's special 'global' values key.",
    "type": [
        "object",
        "null"
    ]
}
```
https://github.com/losisin/helm-values-schema-json/blob/main/docs/upgrading/v2.2-to-v2.3.md
Use Enum and ItemEnum annotations
main
Enum
Use enum:[val1, val2, ...] to restrict a value to a specific set of JSON values. This can include null.
ItemEnum
Use itemEnum:[val1, val2, ...] to apply an enumeration constraint to every item within an array.
```
# Standard enum
service: ClusterIP # @schema enum:[ClusterIP, LoadBalancer, null]

# Enum applied to array items
port: [80, 443] # @schema itemEnum:[80, 8080, 443, 8443]
```
https://github.com/losisin/helm-values-schema-json/blob/main/docs/README.md
Use the Const annotation
main
The const:VALUE annotation restricts an instance to one specific JSON value. When using const, the type keyword is automatically redundant and is dropped from the generated schema.
```
nameOverride: foo # @schema const: foo
```
https://github.com/losisin/helm-values-schema-json/blob/main/docs/README.md
Annotate Meta-Data in YAML using @schema
main
You can add JSON Schema meta-data to your Helm values using the @schema annotation in comments. Supported meta-data keywords include:
- title and description: Adds a title and description to the field. fullnameOverride: bar # @schema title: My title ; description: My description
- examples (since v2.1.0): Provides an array of example values. tag: "" # @schema examples: [v1.2.3, v1.2.3-beta1]
- default: Sets the default value for the field. tolerations: [] # @schema default: [{key: foo, operator: Equal, value: bar, effect: NoSchedule}]
- readOnly: Marks a field as read-only. The :true suffix is optional. tag: "latest" # @schema readOnly
- deprecated: Marks a field as deprecated. The :true suffix is optional. scale: 1 # @schema deprecated
```
fullnameOverride: bar # @schema title: My title ; description: My description
tag: "" # @schema examples: [v1.2.3, v1.2.3-beta1]
image:
  repository: "nginx" # @schema readOnly:true
replicas: 2 # @schema deprecated:true
```
https://github.com/losisin/helm-values-schema-json/blob/main/docs/README.md
Use helm-docs comments for descriptions
main
You can use standard helm-docs comments (starting with # --) to provide descriptions in your generated JSON schema. To enable this, you must use the --use-helm-docs flag when running the helm schema command.
Important Constraints:
- No Detached Comments: The comment must be directly above the property. A comment separated from the property by other lines will not be picked up.
- Ordering with @schema: If you are also using @schema annotations, the @schema annotation must come before the helm-docs description comment. If the description comes first, the @schema annotation might be incorrectly included in the description text by helm-docs.
Example of correct ordering:
```
# @schema maxLength:10
# -- My awesome nameOverride description
nameOverride: "myapp"
```
```
helm schema --use-helm-docs
```
https://github.com/losisin/helm-values-schema-json/blob/main/docs/README.md
Configure Husky for schema generation
main
If you use Husky for git hooks, you can add a pre-commit hook to run the schema generation command automatically.
```
"husky": {
  "hooks": {
    "pre-commit": "helm schema --values values.yaml"
  }
},
```
https://github.com/losisin/helm-values-schema-json/blob/main/README.md
Upgrade helm schema from v1.9 to v2.0
main
When upgrading from any v1.9.x version to v2.0.0, several breaking changes in flag syntax, naming, and configuration must be addressed. The plugin has switched from Go's flag package to pflag, aligning its behavior with Helm.
https://github.com/losisin/helm-values-schema-json/blob/main/docs/upgrading/v1.9-to-v2.0.md

Use the helm-values-schema-json GitHub Action

main

You can automate schema generation in your GitHub workflows using the losisin/helm-values-schema-json-action@v1 action. Use the input parameter to specify the values file(s) to process.

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

helm-values-schema-json

What's inside helm-values-schema-json

Type

Multiple Types

Nullable

Placement Options

Multiple Annotations

Enum

ItemEnum