Real-Time Validation & Diagnostics

The extension provides real-time validation feedback as you edit, powered by strata validate. Errors appear as squiggly underlines in the editor and in VS Code’s Problems panel.

When Validation Runs

Validation is triggered by:

  1. On save (default: enabled)

    • Every time you save a YAML file, the extension runs strata validate

    • Results appear in the Problems panel immediately

  2. While typing (default: disabled)

    • If strata.validateOnType: true, the extension validates after 1.5 seconds of inactivity

    • Useful for tight feedback loops, but can be chatty if you have slow hardware

  3. On demand

    • Command Palette → “Strata: Validate Current File” (validates active editor)

    • Command Palette → “Strata: Validate All Files” (scans workspace with progress bar)

    • Right-click file in Files tree → “Validate”

    • CodeLens → click “Validate” above a YAML document

Problems Panel

Open the Problems panel with Ctrl+Shift+M (or Cmd+Shift+M on Mac). All strata validation errors appear here.

PROBLEMS
─────────────────────────────────────────────────
Strata    ❌ 3 errors, ⚠️ 1 warning

config/main.yaml
  3:5   Error      Unknown field 'specc' (did you mean 'spec'?)
 12:0   Error      Missing required field 'provisioner'

deploy/production.yaml
  8:2   Warning    Deprecated field 'replicas' — use 'instances' instead
 42:1   Error      @infra/modules/api.yaml not found in repository 'infra'

Error anatomy:

config/main.yaml
  3:5   Error      Unknown field 'specc'
  ↑     ↑          ↑
  file  line:col   severity + message

Click an error to jump to that line in the editor.

Error Details

Hover over a red squiggle to see full error details:

Unknown field 'specc' (did you mean 'spec'?)

[Phase 1] Structural validation (Pydantic)
Field: spec
Got value: {...}

The tooltip shows:

  • Error message — what’s wrong

  • Phase — validation phase (Phase 1 = structural, Phase 2 = cross-reference/dynamic)

  • Field — exact field path that failed (e.g., spec.provisioner)

  • Got value — the actual value that didn’t validate (if known)

Quick Fixes

When available, VS Code shows a Quick Fix bulb (💡) next to errors.

Common quick fixes:

  1. Typo suggestion

    • Error: “Unknown field ‘replicas’ (did you mean ‘instances’?)”

    • Fix: “Rename to ‘instances’” → one-click fix

  2. Remove unknown field

    • Error: “Unknown field ‘foo’ — extra fields are not allowed”

    • Fix: “Remove unknown field ‘foo’” → deletes the line

  3. Add missing field

    • Error: “Missing required field ‘provisioner’”

    • Fix: “Add ‘provisioner:’ line” → inserts the field

Access quick fixes via:

  • Click the 💡 icon that appears when hovering over a squiggle

  • Ctrl+. (or Cmd+. on Mac) when your cursor is on the error line

Validation Phases

Strata validation happens in two phases:

Phase 1: Structural (Pydantic)

Checks the YAML against the schema:

  • Unknown fields (extra="forbid")

  • Type mismatches (e.g., string instead of list)

  • Missing required fields

  • Enum value violations

These run first and are always fast.

Phase 2: Dynamic (Cross-Reference & Profile)

Checks references and profile-specific rules:

  • @repo_name/path/file.yaml references resolve correctly

  • Referenced files are valid

  • Secret references exist

  • Environment variables are available in the active profile

These can be slower because they involve file I/O and profile state.

Validation Coverage

Only strata YAML documents are validated. The extension identifies them by checking for apiVersion: strata.* in the first 20 lines.

Valid strata prefixe: strata.huybrechts.xyz/v1

If a YAML file doesn’t have one of these prefixes, it’s not validated by strata (though the YAML extension may still check it).

File Decorations

In the Explorer file tree, validated files show badges:

✓  config/main.yaml         ← green checkmark (validated, no issues)
⚠️  config/test.yaml        ← yellow warning badge
❌ deploy/prd.yaml         ← red error badge

Badges propagate to parent folders, so a single error bubbles up the tree.

Toggle with strata.showFileDecorations setting.

Error Change Notifications

When you save a file and validation runs:

  • New errors → notification appears: “2 new validation errors in config/main.yaml”

  • Errors fixed → notification appears: “Validation passed for deploy/prd.yaml”

  • No change → silent (no notification)

Notifications are only triggered by on-save validation, not by manual validation commands (to avoid spam).

Configuration

  • strata.validateOnSave — Run validation on file save (default: true)

  • strata.validateOnType — Run validation with 1.5s debounce while typing (default: false)

Both can be toggled in Settings without reloading the extension.

Troubleshooting

“Strata validation failed: strata: command not found”

→ The CLI is not in your $PATH. Fix:

  1. Install strata: pip install strata

  2. Or set strata.cliPath to the full path (e.g., /home/user/.local/bin/strata)

“Validation passed but I see errors”

→ You may have other linters enabled (ESLint, YAML extension). Check the “Source” column in the Problems panel to see which tool reported each error.

Validation is slow

→ Phase 2 (cross-reference) validation can be slow with many files. Try:

  1. Disable validateOnType if it’s on

  2. Use on-demand validation (Command Palette → Validate Current File) instead of on-save

  3. Check strata audit list --last to see how long the CLI call took

No validation errors but I expect some

→ The file might not be recognized as a strata document. Check:

  1. Does it have apiVersion: strata.* in the first 20 lines?

  2. Is it in the workspace root or a known repository?

  3. Click “Validate Current File” to force validation (not just on-save)