Home

Welcome to the helm-scribe wiki!

This is a CLI tool that generates documentation and JSON Schema from Helm chart values.yaml files.

helm-scribe reads your values.yaml, extracts metadata from YAML comments, and produces two outputs:

• A markdown parameters table inserted into your README.md between marker comments
• A values.schema.json file for Helm value validation (JSON Schema draft-07)

No external services, no runtime dependencies. One binary, one command, two outputs.

helm-scribe is an annotation-based tool. This means that most of the work (apart from describing the parameters), is done via comments, which contain annotations starting with @.

Schema generation

The generated values.schema.json is placed next to the values file by default. Use --schema-file to override the output path.

The schema is a self-contained JSON Schema draft-07 document. Charts without Kubernetes types produce a flat schema with no $ref or definitions. When a field uses a Kubernetes type (@type k8s:...), the schema gains a top-level definitions block and the field references it with $ref — still draft-07 and compatible with Helm's built-in validator and Artifact Hub.

A property is marked as required when any of the following hold:

• It has an explicit non-null default value (e.g., replicaCount: 1, debug: false, name: "")
• It is an object with children, and at least one descendant is required (recursively)

A property is not required when:

• Its type is nullable (? suffix)
• Its default value is null and it has no children
• It is an object whose descendants are all non-required (e.g., all null without @type)

Note that zero-values (false, 0, "") count as explicit defaults, so fields with these defaults are required. This matches the expectation that a Helm chart defines these values intentionally.

Values that are null without an explicit @type annotation produce an unconstrained schema (no type field, accepts any value) and a warning on stderr. Use @type to specify the intended type for null-valued fields.

The generated schema does not set additionalProperties: false, so extra properties not defined in values.yaml are accepted. This is intentional: Helm passes values through to subcharts, and strict schemas would reject subchart values.

Limitations

• @item paths are split on . separators. YAML keys containing literal dots are not supported in @item path expressions.
• Arrays without a @type or @item annotation produce no items constraint in the schema (a warning is printed).

Exit codes

Code	Meaning
0	Success
1	Fatal error (missing files, parse failure)
2	Warnings present with --strict (output files are still written)

Warnings

Printed to stderr. Common causes:

• Null without @type -- schema entry accepts any value. Fix: add # @type string? or similar.
• Array without @type or @item -- schema won't validate items. Fix: add # @type string[] or # @item annotations.
• Unknown @type -- valid base types are string, integer, number, boolean, object, any, plus k8s:<group>/<version>/<Kind> references.