helm-values-schema

Generate JSON Schema (draft-07) from Helm chart values.yaml files.

Reads default values and helm-docs # -- comments to produce a values.schema.json you can drop next to your chart's values.yaml. Helm uses this file to validate user-supplied values at install/upgrade time.

Install

npm install helm-values-schema

CLI Usage

# From a local file → stdout
helm-values-schema generate --file values.yaml

# From a URL → file
helm-values-schema generate \
  --url https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/charts/ingress-nginx/values.yaml \
  --output values.schema.json

# With options
helm-values-schema generate --file values.yaml \
  --title "my-chart" \
  --description "Schema for my-chart values" \
  --no-defaults \
  --required \
  --output values.schema.json

CLI Options

| Option | Description | |---|---| | -f, --file <path> | Local path to values.yaml | | -u, --url <url> | URL to fetch values.yaml from | | -o, --output <path> | Output file path (default: stdout) | | --title <title> | Schema title | | --description <desc> | Schema description | | --no-defaults | Omit default values from schema | | --required | Mark non-null fields as required | | --header <key:value> | HTTP headers (repeatable) | | --timeout <ms> | Request timeout (default: 30000) |

Programmatic API

generateSchema(content, options?)

Generate a schema from a YAML string:

import { generateSchema } from 'helm-values-schema';

const yaml = `
# -- Number of replicas
replicas: 3
image:
  # -- Docker image repository
  repository: nginx
  tag: "1.0"
enabled: true
config: {}
extra: null
`;

const schema = generateSchema(yaml, { title: 'my-chart' });
console.log(JSON.stringify(schema, null, 2));

Output:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "my-chart",
  "type": "object",
  "properties": {
    "replicas": {
      "description": "Number of replicas",
      "type": "integer",
      "default": 3
    },
    "image": {
      "type": "object",
      "properties": {
        "repository": {
          "description": "Docker image repository",
          "type": "string",
          "default": "nginx"
        },
        "tag": {
          "type": "string",
          "default": "1.0"
        }
      }
    },
    "enabled": {
      "type": "boolean",
      "default": true
    },
    "config": {
      "type": "object",
      "additionalProperties": true
    },
    "extra": {}
  }
}

generateSchemaFromSource(source, options?)

Load from a URL or file path and generate:

import { generateSchemaFromSource } from 'helm-values-schema';

const schema = await generateSchemaFromSource(
  'https://raw.githubusercontent.com/.../values.yaml',
  { title: 'ingress-nginx' }
);

Options

interface GenerateOptions {
  /** Include $schema declaration in root (default: true) */
  includeSchemaDeclaration?: boolean;
  /** Include default values in the schema (default: true) */
  includeDefaults?: boolean;
  /** Mark non-null fields as required (default: false) */
  markRequired?: boolean;
  /** Schema title */
  title?: string;
  /** Schema description */
  description?: string;
  /** HTTP headers for authenticated requests */
  headers?: Record<string, string>;
  /** Request timeout in ms (default: 30000) */
  timeout?: number;
}

Lower-level API

For more control, use the parser and builder separately:

import { parseValuesYaml, buildSchema } from 'helm-values-schema';

const tree = parseValuesYaml(yamlContent);
// Inspect or modify the parsed tree...
const schema = buildSchema(tree, { includeDefaults: false });

Type Inference Rules

| YAML Value | JSON Schema | |---|---| | "hello", "" | { "type": "string" } | | 3, 101 | { "type": "integer" } | | 1.5 | { "type": "number" } | | true, false | { "type": "boolean" } | | null, ~ | {} (permissive — accepts any value) | | {} | { "type": "object", "additionalProperties": true } | | [] | { "type": "array", "items": {} } | | [80, 443] | { "type": "array", "items": { "type": "integer" } } | | nested object | { "type": "object", "properties": { ... } } |

helm-docs Comments

Comments following the # -- convention (used by helm-docs) are extracted as description fields:

# -- Override the deployment namespace
namespaceOverride: ""

Produces:

{
  "namespaceOverride": {
    "description": "Override the deployment namespace",
    "type": "string",
    "default": ""
  }
}

Multi-line # -- comments are joined into a single description.

Examples

Pre-generated schemas for popular charts are in the examples/ directory:

• ingress-nginx-values.schema.json
• grafana-values.schema.json

License

MIT