Editor setup¶

Configure your editor so it validates Lakehouse Plumber (LHP) YAML against the bundled JSON schemas and offers completions and hover docs on every key. This page covers VS Code (auto-configured by lhp init), Cursor, and any editor that speaks the YAML Language Server protocol.

For background on why LHP ships JSON schemas, see Architecture.

Use the auto-configured setup from `lhp init`¶

lhp init writes a ready-to-use VS Code configuration into every new project. You do not need to do anything else if you scaffolded the project with the CLI.

Run the initializer from an empty directory:

mkdir my_lakehouse && cd my_lakehouse
lhp init my_lakehouse

The command creates the project layout and, alongside it, a .vscode/ folder:

.vscode/ contents after lhp init¶

.vscode/
  ├── settings.json          # Maps YAML files to JSON schemas
  └── schemas/
      ├── flowgroup.schema.json
      ├── template.schema.json
      ├── preset.schema.json
      ├── project.schema.json
      ├── substitution.schema.json
      ├── blueprint.schema.json
      └── instance.schema.json

Open the project in VS Code, install the YAML extension by Red Hat if you do not already have it, and editing any file under pipelines/, presets/, templates/, or substitutions/ triggers schema validation and IntelliSense.

Note

The schemas in .vscode/schemas/ are copies pinned to the LHP version that ran lhp init. Run lhp init in a sibling directory and copy the updated files when you upgrade LHP, or follow the manual steps below to refresh them.

Configure VS Code in an existing project¶

If your project predates lhp init or you removed .vscode/, recreate the configuration in four steps.

1. Install the YAML extension¶

Install YAML by Red Hat (extension ID redhat.vscode-yaml) from the Extensions marketplace. The extension ships the YAML Language Server that VS Code uses to validate against JSON Schema.

2. Copy the schemas into your project¶

LHP keeps the canonical schemas under src/lhp/schemas/ in the source tree and bundles them in the installed package. Copy them into .vscode/schemas/:

mkdir -p .vscode/schemas
python -c "from importlib.resources import files; import shutil; \
  src = files('lhp.schemas'); dest = '.vscode/schemas'; \
  [shutil.copy(src / name, dest) for name in [ \
    'flowgroup.schema.json', 'template.schema.json', \
    'preset.schema.json', 'project.schema.json', \
    'substitution.schema.json', 'blueprint.schema.json', \
    'instance.schema.json']]"

This pulls the schemas straight from the installed lhp package, so they match the CLI version you are using.

3. Create `.vscode/settings.json`¶

Write the schema-to-glob mapping that lhp init would have generated:

.vscode/settings.json¶

{
  "yaml.schemas": {
    "./schemas/flowgroup.schema.json": [
      "pipelines/**/*.yaml",
      "pipelines/**/*.yml"
    ],
    "./schemas/template.schema.json": [
      "templates/**/*.yaml",
      "templates/**/*.yml"
    ],
    "./schemas/preset.schema.json": [
      "presets/**/*.yaml",
      "presets/**/*.yml"
    ],
    "./schemas/project.schema.json": [
      "lhp.yaml",
      "lhp.yml"
    ],
    "./schemas/substitution.schema.json": [
      "substitutions/**/*.yaml",
      "substitutions/**/*.yml"
    ],
    "./schemas/blueprint.schema.json": [
      "blueprints/**/*.yaml",
      "blueprints/**/*.yml"
    ],
    "./schemas/instance.schema.json": [
      "instances/**/*.yaml",
      "instances/**/*.yml"
    ]
  },
  "yaml.format.enable": true,
  "yaml.validate": true,
  "yaml.completion": true,
  "yaml.hover": true,
  "files.associations": {
    "*.yaml": "yaml",
    "*.yml": "yaml"
  }
}

The glob patterns mirror LHP’s project layout. If you keep FlowGroups in a custom directory, add it to the relevant yaml.schemas entry.

4. Reload the window¶

Run Developer: Reload Window from the command palette (Ctrl+Shift+P or Cmd+Shift+P). VS Code rereads settings.json and binds the schemas.

Configure Cursor and other LSP editors¶

Cursor uses the same YAML Language Server as VS Code, so the .vscode/ configuration above works without modification. Install the YAML extension from the Open VSX registry and reload.

For other editors (Neovim with yaml-language-server, JetBrains IDEs, Helix, Zed), point the language server’s yaml.schemas setting at the same files:

Generic yaml-language-server config¶

yaml.schemas:
  ./.vscode/schemas/flowgroup.schema.json:
    - pipelines/**/*.yaml
  ./.vscode/schemas/template.schema.json:
    - templates/**/*.yaml
  ./.vscode/schemas/preset.schema.json:
    - presets/**/*.yaml
  ./.vscode/schemas/project.schema.json:
    - lhp.yaml
  ./.vscode/schemas/substitution.schema.json:
    - substitutions/**/*.yaml

JetBrains IDEs (PyCharm, IntelliJ) configure JSON Schema mappings under Settings -> Languages & Frameworks -> Schemas and DTDs -> JSON Schema Mappings. Add one mapping per schema file with the file pattern from the table above.

Verify IntelliSense is working¶

Run this two-minute check to confirm the editor binds the schemas.

Open a file under pipelines/, for example pipelines/bronze/customers.yaml.
Start a new line at the top level and type pi. The completion popup must suggest pipeline with the description “Pipeline name”.
Add an invalid action type:
```
pipeline: bronze
flowgroup: customers
actions:
  - name: load_data
    type: not_a_real_type
```
VS Code must underline not_a_real_type and report that the value is not one of load, transform, write, or test.
Hover over actions. The tooltip must show the property description from flowgroup.schema.json.

If all four signals appear, the editor is configured correctly.

Troubleshoot a silent setup¶

If completions or validation do not appear, work through these checks in order:

Confirm the YAML extension is enabled. Disabling and re-enabling it forces a language-server restart.
Open .vscode/settings.json and verify the relative paths under yaml.schemas resolve. VS Code resolves them against the workspace root, so ./schemas/flowgroup.schema.json only works when the schemas live in .vscode/schemas/ (the leading ./ is workspace-relative, not file-relative).
Reload the window with Developer: Reload Window after any edit to settings.json.
Check the YAML output channel (View -> Output, then pick “YAML” from the dropdown) for schema-load errors.

Tip

Refresh your schemas after every LHP upgrade. Step 2 of the manual setup reads schemas from the installed package, so re-running that one-liner picks up new keys and enum values added in the release.

Editor setup¶

Use the auto-configured setup from lhp init¶

Configure VS Code in an existing project¶

1. Install the YAML extension¶

2. Copy the schemas into your project¶

3. Create .vscode/settings.json¶

4. Reload the window¶

Configure Cursor and other LSP editors¶

Verify IntelliSense is working¶

Troubleshoot a silent setup¶

See also¶

Use the auto-configured setup from `lhp init`¶

3. Create `.vscode/settings.json`¶