SYSTEM Cited by 1 source

YAML Language Server

Definition

The YAML Language Server (redhat-developer/yaml-language-server) is an LSP implementation for YAML, maintained by Red Hat. Any LSP-capable editor (VSCode, Neovim with coc.nvim or native LSP, IntelliJ, Sublime LSP, …) can attach to it to get schema-driven YAML editing:

• Autocompletion of keys and values.
• Live validation against a JSON Schema with red-squiggle error display.
• Hover tooltips sourced from schema description fields.
• Format-on-save.
• Symbol navigation.

The # yaml-language-server: comment directive

The load-bearing feature for per-file schema binding is a YAML comment at the top of the file that points the language server at a schema:

# yaml-language-server: $schema=schema/config_schema.json
metadata:
  accounts:
    - id: ...

The server reads the directive and loads the schema (local path or HTTP URL); the rest of the file is validated against it in real time. The same mechanism is how Kubernetes manifest editors, GitHub Actions workflow editors, and SwaggerHub YAML validators work out of the box.

Seen in

• sources/2024-01-22-zalando-tale-of-metadpata-the-revenge-of-the-supertools — named directly in Zalando's 2024-01 metadpata postmortem as the IDE-side enforcement point of their triple-redundant jsonschema enforcement stack. "We also did some small quality of life improvements to enable autocompletion and schema validation in our local IDEs, which mitigates the possibility of typos and errors and is simple to set up:

  ```

  yaml-language-server: $schema=schema/config_schema.json

  (your config) ```" Partners with systems/pre-commit (commit-time hook) and the CI pipeline (server-side hook) to form three redundant enforcement points on one JSON Schema.

Relationship to adjacent tools

• pre-commit — commit-time enforcement. YAML Language Server is IDE-time enforcement of the same rules.
• Generic JSON Schema validators (ajv, jsonschema, …) — used by pre-commit hooks and CI. YAML Language Server uses the same JSON Schemas but lifts them into editor UX.
• Kubernetes kubeconform / kubeval — Kubernetes- specific schema validators. YAML Language Server is generic YAML; a Kubernetes-specific editor setup points it at the Kubernetes OpenAPI schemas.
• JSON Schema Store (schemastore.org) — central registry of JSON Schemas keyed by filename pattern; the YAML Language Server can auto-select a schema for known filename patterns.

Caveats

• IDE enforcement is advisory. Developers can ignore red squiggles; only commit-time and CI enforcement actually block bad configs. The YAML Language Server sits at the earliest, weakest enforcement point — catching the most typos in principle but blocking none in practice.
• Not every editor uses the same LSP client. Config burden varies; some editors need a plugin (yaml.schemas in VSCode, coc-yaml in Neovim, etc.).
• Schema comment must be preserved through any templating or codegen; templated YAML may not carry the comment through to the rendered file.
• Schema $id / $ref resolution — URL-based schemas need network access at editor startup; large teams mirror internally.

Related

• systems/pre-commit
• concepts/jsonschema-config-validation
• patterns/jsonschema-validated-config-both-local-and-ci
• companies/zalando