Editor Support

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

https://orchstep.dev/schema.json

Point any editor with a YAML language server at it and you get autocomplete for every field, hover descriptions, and red squiggles the moment a workflow has a typo or the wrong shape - before you ever run it.

Option 1: inline schema comment (works everywhere)

Add one line to the top of your workflow. Any editor running the yaml-language-server (VS Code, JetBrains, Neovim, Helix) picks it up with zero extra config:

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

This is the most portable option - the schema travels with the file, so teammates and CI logs see the same validation regardless of editor settings.

Option 2: VS Code workspace settings

Install the YAML extension (redhat.vscode-yaml), then map the schema to your workflow files 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: test.yml, files under tasks/, and orchstep-module.yml are different document shapes, so they should not be validated against the workflow schema.

Option 3: SchemaStore (automatic)

OrchStep is being submitted to SchemaStore, the catalog the YAML extension uses by default. Once the entry is merged, any file named orchstep.yml gets validation automatically - no $schema line, no settings. Until then, use Option 1 or 2.

What you get

• Autocomplete for tasks, steps, vars, env, modules, function keys (shell, http, git, assert, ...), and their options.
• Hover docs pulled straight from the schema descriptions.
• Inline errors for unknown keys, wrong types, and missing required fields - the class of mistake that otherwise only surfaces at run time.

The schema is also vendored in the repo at .vscode/orchstep-schema.json and wired into the workspace settings, so contributors get validation out of the box.