Autocomplete & validation for orchstep.yml in your editor

YAML is forgiving in the worst way: a misspelled key or a value of the wrong shape parses fine and then fails at run time, sometimes minutes into a pipeline. The fix is a schema your editor understands — so the red squiggle shows up while you type, not when CI breaks.

OrchStep publishes a JSON Schema for orchstep.yml at a stable URL:

https://orchstep.dev/schema.json

It is a real, complete Draft-07 schema (title OrchStep Workflow) with every top-level key, every step field, and the func value set enumerated. Any editor running the yaml-language-server — VS Code, JetBrains, Neovim, Helix — turns that into live tooling.

The one-line setup that travels with the file

Add a single comment to the top of your workflow. No extension config, no settings file — the schema reference lives in the file, so teammates and CI logs see the same validation:

# yaml-language-server: $schema=https://orchstep.dev/schema.json
name: deploy
tasks:
  build:
    steps:
      - name: compile
        func: shell
        do: make build

That is the whole setup. Open the file and you immediately get autocomplete on tasks, steps, and step fields, hover text pulled from the schema, and an error the moment something is the wrong shape.

What the schema actually catches

The schema declares additionalProperties: false and enumerates the valid keys, so an unknown field is a hard error — not a silently-ignored typo. This is the exact class of mistake that otherwise survives until run time. Write a step with the wrong key and you find out instantly:

name: deploy
tasks:
  build:
    steps:
      - name: compile
        shell: make build      # not a real key

name: deploy
tasks:
  build:
    steps:
      - name: compile
        func: shell            # func + do
        do: make build

The CLI agrees with the editor, byte for byte — the binary parses against the same field set and rejects the unknown key with the list of valid ones:

unknown step key 'shell'. Valid keys: args, catch, desc, description, do,
dotenv, elif, else, env, finally, flags, func, if, loop, ...

The value of the schema is that you see that in the editor, before saving — not from a failed run. The func field is an enum (shell, http, assert, git, transform, render, wait, prompt), so autocomplete offers exactly those and flags anything else.

VS Code: map it to your files

If you would rather not put the comment in every file, install the Red Hat YAML extension and map the schema in .vscode/settings.json:

{
  "yaml.schemas": {
    "https://orchstep.dev/schema.json": [
      "**/orchstep.yml",
      "!**/tasks/**",
      "!**/test.yml",
      "!**/orchstep-module.yml"
    ]
  },
  "yaml.validate": true,
  "yaml.completion": true,
  "yaml.hover": true
}

The exclusions matter: task files under tasks/, test.yml, and orchstep-module.yml are different document shapes and should not be checked against the workflow schema.

What you gained

The honest boundary

A schema validates shape, not meaning. It cannot know that {{ vars.region }} is never supplied by any environment, or that a task calls one that does not exist — that is semantic, and it is what orchstep lint and orchstep validate are for. Think of it as two layers: the schema catches typos and wrong types as you edit; the CLI catches logic errors before you ship. Use both.

Where to go next

• Editor Support — all three setup options, including SchemaStore
• CLI Reference — lint and validate for the semantic layer
• Output & Exit Codes — how validation failures surface in CI

Already have an orchstep.yml open? Paste the # yaml-language-server line at the top and watch the editor light up.