# yaml-language-server: YAML editing through LSP

> yaml-language-server adds validation, schema-aware completion, hover information, formatting, and document symbols to YAML editors through the Language Server Protocol. It is aimed at developers and platform teams that work with JSON Schema, Kubernetes resources, or older YAML syntax.

**redhat-developer/yaml-language-server** — Language Server for YAML Files

- Repository: https://github.com/redhat-developer/yaml-language-server
- Stars: 1,537 · Forks: 355
- Language: TypeScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/redhat-developer-yaml-language-server

## Why yaml-language-server targets schema-governed YAML

yaml-language-server addresses a specific gap in plain text editing. A YAML file can be syntactically well formed while still containing misspelled keys, invalid value types, or properties that its intended schema does not permit. The server exposes YAML-aware editor assistance over the Language Server Protocol, which lets an editor request diagnostics and other document intelligence without adopting a YAML-specific IDE.

The intended users include developers editing configuration, platform engineers maintaining Kubernetes resources, and teams that publish or consume schemas through SchemaStore. Its usefulness depends on schema association. Validation can detect malformed YAML, while schema validation can report messages such as an invalid node type or an additional property. Completion, hover descriptions, defaults, and structural suggestions are also schema-driven according to the README.

This is an editor service rather than a general-purpose YAML policy engine. The documented feature set does not include a command for transforming files, enforcing organization-wide naming rules, or resolving business semantics. It also does not guarantee that an arbitrary schema will yield useful completion. Schema availability and association determine much of the result.

## The LSP request and document processing path

The repository identifies the implementation as TypeScript and exposes a Node.js package with the `yaml-language-server` executable. Its package metadata points to an ES module entry at `./out/src/index.js`, while the container entry point starts `out/src/server.js` with `--stdio`. This indicates a process-based LSP server that communicates through standard input and output.

At the document level, version `1.0.0` and later use `eemeli/yaml` as the parser. The README says that parser strictly enforces the selected YAML specification. YAML `1.2` is the default, which matters because older files may depend on YAML `1.1` behavior. Editors can set `yaml.yamlVersion` to `1.1` for those files.

Schema validation supports JSON Schema `draft-04`, `draft-07`, `2019-09`, and `2020-12`. The package dependencies include AJV packages for draft-04 validation and related JSON Schema processing. `picomatch` is used in the dependency set, which is consistent with glob-based schema mapping through `yaml.schemas`. For online schema discovery, the documented catalog endpoint defaults to `https://www.schemastore.org/api/json/catalog.json`.

The server does not treat every YAML document as schema-backed. `yaml.schemaStore.enable` defaults to `true`, but users can disable it, define explicit associations, or disable schema detection for selected glob patterns. Modelines still apply when schema detection is disabled, as the README specifically notes.

## Validation, completion, hover, and formatting in an editor

Validation covers two layers. The first checks whether the whole document is valid YAML and can report parse-structure failures. The second uses an associated schema to check keys, node types, child-node validity, and additional properties. `yaml.validate` controls the feature and defaults to `true`.

Completion is more dependent on context. It can offer YAML keys, values, and structural content based on the associated schema. When a schema defines defaults, scalar completions may include those defaults. By default, properties that are not required can still appear when they have default values. Setting `yaml.disableDefaultProperties` to `true` suppresses that class of completion. Another setting, `yaml.suggest.parentSkeletonSelectedFirst`, changes empty-object completion behavior by requiring a parent skeleton selection before the remaining properties are offered. In a non-empty object, the README says this setting does not apply and all properties and skeletons are returned.

Hover can display schema descriptions, while `yaml.hoverAnchor` adds anchor information and `yaml.hoverSchemaSource` adds schema source information. Both default to `true`. Formatting is enabled by default through `yaml.format.enable`. It supports whole-document formatting and on-type formatting after a newline, including indentation for mappings and array items. The formatter exposes print width, quote style, bracket spacing, prose wrapping, and trailing commas.

Document symbols provide a hierarchy of YAML nodes. `yaml.maxItemsComputed` limits both document symbols and folding regions to `5000` by default. That ceiling is a meaningful constraint for generated or unusually large files: the server intentionally avoids unlimited computation for these features.

## Installing yaml-language-server and starting the server

The package manifest names the npm package `yaml-language-server`, declares the `yaml-language-server` binary, and requires Node.js `>=22.13.0`. The README does not give a complete editor installation procedure or a ready-to-copy LSP client configuration, so it would be misleading to invent one. The package manifest and Dockerfile provide the documented package identity and container startup path instead.

For contributors using the repository scripts, `package.json` defines compilation, watching, and testing commands. The compile command writes the project into `out/`, where the Docker entry point expects the server module:

```bash
npm run compile
```

After a successful compilation, the container command starts the compiled server over standard input and output. The repository Dockerfile does not include an editor client, so it produces the server process but does not demonstrate a complete validation request.

The package executable mapping indicates the command name available to an installed package:

```json
{
  "bin": {
    "yaml-language-server": "bin/yaml-language-server"
  }
}
```

An editor user needs to map that executable to an LSP client and enable stdio communication. The precise client setting is outside the README. The first visible result should be YAML diagnostics or completion once a YAML document is opened, but only after the editor has established the language-server connection.

## A Docker deployment for editor integration

The repository provides a Dockerfile for packaging the server with Node.js. It copies the project into `/yaml-language-server`, installs dependencies, runs `npm run build`, and starts `out/src/server.js` with `--stdio`. This is the clearest documented way to produce a runnable server process without inventing a client configuration.

The Dockerfile build stage is:

```dockerfile
FROM node:lts

COPY . /yaml-language-server

RUN cd /yaml-language-server && \
    npm install && \
    npm run build

ENTRYPOINT [ "node", "/yaml-language-server/out/src/server.js" ]
CMD [ "--stdio" ]
```

There is an important mismatch to account for when reading this file: the Dockerfile uses the `node:lts` image, while `package.json` states an engine requirement of `>=22.13.0`. A moving LTS tag may change over time, and the Dockerfile does not pin a Node.js release. Editors or operators should therefore check the effective Node.js version rather than assuming that the image always satisfies the package manifest.

The container is also not a complete IDE. It exposes a server process, not a user interface. Schema downloads may require network access unless schemas are associated locally. The documented `http.proxy` and `http.proxyStrictSSL` settings affect schema downloads, but the README does not describe offline caching guarantees.

## Schema selection, YAML versions, and network dependencies

The server has several settings that can change results substantially. `yaml.yamlVersion` accepts `1.2` or `1.1`, with `1.2` as the default. This is not merely a parser preference. A document authored under YAML `1.1` may contain syntax or scalar semantics that a strict YAML `1.2` parser rejects or interprets differently.

Schema associations are defined with `yaml.schemas`, which maps files using glob patterns. `yaml.schemaStore.enable` controls automatic association from the SchemaStore catalog. The catalog URL defaults to `https://www.schemastore.org/api/json/catalog.json`. For Kubernetes custom resources, `yaml.kubernetesCRDStore.enable` defaults to `true`, and the default CRD schema base URL is `https://raw.githubusercontent.com/datreeio/CRDs-catalog/main`.

The server can also accept custom tags through `yaml.customTags`. Tags may specify only a tag name, a YAML node type, or both a node type and schema return type. Supported node types are `scalar`, `sequence`, and `mapping`; supported return types are `string`, `number`, `integer`, `boolean`, `null`, `array`, and `object`. This is useful for organizations whose YAML dialect contains domain-specific tags, but the configuration must describe the tag precisely.

A potentially damaging global setting is `yaml.disableAdditionalProperties`. When enabled, it sets `additionalProperties` to `false` for all objects. That can reject documents that are valid under local schemas but contain extension fields. It should be understood as a global policy switch, not a harmless cleanup.

## Limits, license, and maintenance considerations

The main limitation is that intelligent features depend on schema quality and availability. If a file is not associated with a schema, syntax validation can still apply, but key completion, descriptions, defaults, and schema-based diagnostics cannot be inferred with the same precision. Automatic SchemaStore matching does not replace an explicit `yaml.schemas` entry for internal formats.

There is another operational limit. The server defaults `yaml.maxItemsComputed` to `5000` for symbols and folding regions. Large generated YAML files may therefore receive reduced structural intelligence. The README does not document a general rollback procedure, schema cache behavior, or an offline fallback for unavailable remote schemas, so those points should be verified in the client environment before adoption.

The project is not archived, and the last push was on 2026-10-16. No GitHub releases are listed, so the repository facts do not establish a formal release cadence. The package version in `package.json` is `2.0.0`, and the repository contains `CHANGELOG.md`, but the README does not summarize individual upgrade changes. Upgrade review should therefore focus on `CHANGELOG.md`, Node.js compatibility, and changes to parser or schema behavior.

The package declares the MIT license. That is relevant for redistribution and integration review, but this article does not provide legal advice. The practical upgrade costs are likely to come from client configuration changes, schema draft compatibility, YAML-version changes, and Node.js runtime requirements rather than from license restrictions alone.

## Conclusion

Adopt yaml-language-server when an LSP-capable editor is the main interface for schema-governed YAML. Do not choose it as a standalone validation command or assume its SchemaStore integration covers every internal schema. Verify first that your client can pass the documented `yaml.*` settings, that Node.js meets `>=22.13.0`, and that your schemas work with the selected YAML version and JSON Schema draft.

## FAQ

### How do I install yaml-language-server?

The repository identifies the npm package as `yaml-language-server` and provides a `yaml-language-server` binary. The README does not include a complete editor installation or client configuration, but the Dockerfile documents building the project and starting `out/src/server.js` with `--stdio`.

### What Node.js version does yaml-language-server require?

The package manifest declares `node` `>=22.13.0`. The Dockerfile uses `node:lts`, so the effective image version should be checked against that engine requirement.

### Does yaml-language-server work without JSON Schema?

It can validate whether a document is valid YAML without a schema, according to the README. Schema-driven completion, hover descriptions, defaults, and detailed property diagnostics depend on an associated schema.

### Which YAML and JSON Schema versions are supported?

The default YAML version is `1.2`, and `yaml.yamlVersion` can be set to `1.1`. Schema validation supports JSON Schema `draft-04`, `draft-07`, `2019-09`, and `2020-12`.

## Sources

- [Issues](https://github.com/redhat-developer/yaml-language-server/issues)
- [License: MIT](https://github.com/redhat-developer/yaml-language-server/blob/main/LICENSE)
- [README](https://github.com/redhat-developer/yaml-language-server/blob/main/README.md)
- [redhat-developer/yaml-language-server on GitHub](https://github.com/redhat-developer/yaml-language-server)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/redhat-developer-yaml-language-server