YAML Language Server

The YAML Language Server provides YAML language features over the Language Server Protocol (LSP). Key features include:

• YAML validation: Detects valid YAML syntax and reports diagnostics like invalid keys, invalid types, or missing nodes.
• Document symbols: Provides a hierarchical view of YAML nodes.
• Completion: Suggests keys, values, and structures based on associated JSON schemas, including schema defaults.
• Hover: Displays schema descriptions, anchor information (if yaml.hoverAnchor is enabled), and schema source information (if yaml.hoverSchemaSource is enabled).
• Formatting: Formats YAML documents and supports on-type formatting (e.g., automatic indentation on newline).

Note: Completion and hover content are driven by schemas. The server uses eemeli/yaml for parsing, defaulting to YAML spec version 1.2.

When multiple schema sources or disabling mechanisms are present, the server resolves them in this order (highest to lowest):

1. Modeline
2. Inline $schema property
3. Registered custom schema provider
4. yaml.disableSchemaDetection
5. yaml.schemas
6. json/schemaAssociations notification
7. SchemaStore

The build process generates multiple module formats to support various server-side loaders and browser bundlers (like webpack):

• CommonJS: Generated in the out/server/src directory.
• UMD (Universal Module Definition): Generated in the lib directory.
• ES Modules (ESM): Generated in the lib directory.

You can integrate the server into your tools using several methods:

Via npm (Global Install)

npm install -g yaml-language-server
yaml-language-server --stdio

Via Local Build

Clone the repository, build it, and run the output file:

git clone https://github.com/redhat-developer/yaml-language-server.git
cd yaml-language-server
npm install
npm run build
node ./out/server/src/server.js --stdio

Via Docker

docker run -i --rm quay.io/redhat-developer/yaml-language-server:latest

Supported communication channels:

• --stdio
• --socket=<port>
• --node-ipc

To develop on the yaml-language-server repository, ensure you have Node.js (v18.18.0 or higher) and npm installed. Follow these steps to prepare the environment:

1. Fork and clone the repository.
2. Install dependencies using npm install.
3. Build the server using npm run build.

After building, the main server output is located in out/server/src.

cd yaml-language-server
npm install
npm run build

You can hide specific diagnostics or all diagnostics on a line by adding a suppression comment immediately before the line.

To suppress all diagnostics on a line, use: # yaml-language-server-disable

To suppress specific diagnostics, append one or more comma-separated substrings that match the diagnostic message. The matching is case-insensitive.

# yaml-language-server-disable
version: 123

# Suppress specific messages (case-insensitive)
# yaml-language-server-disable Incorrect type, not accepted
version: 123

Use the following command to execute the test suite for the language server:

npm test

To stop schema-based diagnostics for a file while still allowing YAML syntax error reporting, you can use one of the following methods:

1. Using a modeline

Add a comment at the top of the file using either the standard or IntelliJ-compatible format:

• # yaml-language-server: $schema=none
• # $schema: none

2. Using yaml.disableSchemaDetection

Configure the yaml.disableSchemaDetection setting in your editor/client with glob patterns to prevent schemas from being applied to specific files.

{
  "yaml.disableSchemaDetection": "**/.github/workflows/*.yaml"
}

You can extend YAML with application-specific syntax using the yaml.customTags setting. Each entry follows one of these formats:

• !Tag: Treats the tag as a scalar.
• !Tag nodeType: Specifies the YAML node type (scalar, sequence, or mapping).
• !Tag nodeType:returnType: Specifies the node type and the schema type for validation (e.g., string, number, integer, boolean, null, array, object).

Note: scalar, sequence, and mapping are aliases for string, array, and object respectively.

{
  "yaml.customTags": [
    "!Scalar-example",
    "!Seq-example sequence",
    "!Mapping-example mapping",
    "!Seq-as-string-example sequence:string"
  ]
}

When multiple schemas match a YAML document, the SchemaPriority enum determines which one wins. You can set the priority within the schemas array in LanguageSettings using the priority key.

Available priorities:

• SchemaStore = 1
• SchemaAssociation = 2
• Settings = 3
• SchemaDetectionDisabled = 4

You can suppress YAML diagnostics (errors, warnings, etc.) by adding a special comment on the line immediately preceding the line containing the diagnostic.

Usage Patterns

• Suppress all diagnostics on the next line: Use the comment without any additional text.
• Suppress specific diagnostics: Provide one or more comma-separated substrings. A diagnostic will be suppressed if its message contains any of these substrings (case-insensitive).

Examples

# yaml-language-server-disable
key: value  # All diagnostics on this line are suppressed

# yaml-language-server-disable Incorrect type
key: 123    # Only diagnostics containing "Incorrect type" are suppressed

# yaml-language-server-disable Incorrect type, not accepted
key: unknown # Diagnostics containing "Incorrect type" OR "not accepted" are suppressed