`helix schemas`¶

Emit machine-readable JSON Schema artifacts for every component the binary knows about, plus a curated schema for the top-level YAML DSL. Use these with yaml-language-server, IDE autocomplete, or any CI linter that consumes JSON Schema.

Usage¶

helix schemas              # writes ./schemas/components/*.json + ./schemas/dsl/workflow.json
helix schemas <out-dir>    # writes <out-dir>/components/*.json + <out-dir>/dsl/workflow.json
helix schemas --print      # prints one combined JSON doc to stdout

Flags¶

Flag	Default	Description
`--print`	off	Write a single combined JSON document (components + DSL) to stdout instead of files.
`-h`, `--help`	—	Print usage and exit.

The first non-flag argument is the output directory. Defaults to ./schemas/.

What is produced¶

<out-dir>/
├── components/
│   ├── <scheme>.json     # one schema per Describable component
│   └── index.json        # summary {scheme, description, uri_format, role}
└── dsl/
    └── workflow.json     # top-level YAML DSL schema (workflow + step + rag-* bodies)

Each component schema:

is JSON Schema draft-07
$id: a stable URL that identifies the component's schema
properties: one entry per ComponentDescriptor.Param, typed against the descriptor (boolean, integer, number, duration, enum, default string). Enum descriptors emit enum: [...]. The duration type maps to string with a regex pattern + an x-helix-type: duration hint.
required: every param flagged Required in the descriptor
vendor extensions: x-helix-scheme, x-helix-uri-format, x-helix-role
additionalProperties: false

The DSL schema (dsl/workflow.json) describes the recognised top-level keys (workflows:, connectors:, error-handlers:, imports:) and the inner workflow / step shapes. The RAG step bodies (rag-ingest, rag-chunk, rag-embed, rag-raptor, rag-retrieve, rag-synthesize, rag-docstore, rag-graph-build, rag-graph-query) are described in full so editor autocomplete works for them. Non-RAG steps accept arbitrary objects.

Behavior notes¶

Requires $HELIX_LICENSE. Verified at process start.
Output is deterministic (schemes sorted alphabetically) — safe to commit and diff.
--print writes a combined doc with components: {scheme: schema} plus dsl: {workflow schema}. Useful for CI consumers that want a single artifact.
Files are written with mode 0644; directories with mode 0755.
Tells you how to enable yaml-language-server at the end: add # yaml-language-server: $schema=<dsl/workflow.json> to the top of your YAML.

Examples¶

Generate every schema into ./schemas/:

helix schemas

Generate to a custom directory:

helix schemas build/schemas

Pipe a combined doc into jq:

helix schemas --print | jq '.components | keys'

Wire VS Code's YAML extension to the DSL schema (in .vscode/settings.json):

{
  "yaml.schemas": {
    "./schemas/dsl/workflow.json": ["*.yaml", "*.yml"]
  }
}

Source¶

cmd/helix/schemas.go lines 33-115 (cmdSchemas), 122-177 (buildComponentSchema), 202-289 (dslWorkflowSchema), 320-450 (dslStepSchema).

helix schemas¶