YAML Language Server

Common errors

• No errors are appearing in the LSP log... not seeing syntax highlighting, autocomplete, or suggestions in YAML files

  cause The language server is not being correctly started, or the LSP client is failing to establish communication or send necessary requests (e.g., 'initialize', 'textDocument/didOpen').
  fix Verify that the `yaml-language-server` executable path is correct in your LSP client's configuration (e.g., Neovim's `lspconfig`, VSCode extension settings). Check client/server logs for any connection errors. Ensure Node.js is installed and accessible in the environment where the server runs.

• mapping values are not allowed in this context at line X column Y

  cause This error typically indicates an indentation issue, a missing colon (`:`), or an attempt to use a non-scalar value (like a map or sequence) where a scalar is expected, violating YAML syntax rules.
  fix Carefully review the specified line and column for incorrect indentation, missing key-value separators, or misplaced complex structures. Online YAML validators (e.g., YAML Lint) can help pinpoint syntax errors.

• Incorrectly flagging 'Missing property "$ref"' for OpenAPI 3.0.X

  cause The language server's schema validation might incorrectly interpret OpenAPI 3.0.X schemas, particularly regarding the `$ref` keyword, leading to false-positive validation errors.
  fix Check for updates to the `yaml-language-server` and `vscode-yaml` extensions, as this was a known issue that might have been resolved in newer versions. Ensure your OpenAPI schema is valid and accessible, and potentially simplify `$ref` usage if possible.

Warnings

• breaking Starting from version 1.0.0, the YAML Language Server switched its internal parser to `eemeli/yaml`. This change results in stricter adherence to the specified YAML specification, which might cause previously tolerated, non-compliant YAML files to now trigger validation errors.
  Fix: Review and update YAML files to strictly comply with the YAML 1.2 specification (or 1.1 if configured via `yaml.yamlVersion`). Pay close attention to indentation, quoted strings, and tag usage.
• gotcha When working with YAML files containing multiple documents (separated by `---`), Intellisense completion and sometimes other language features may break or behave unexpectedly, especially in certain LSP client integrations.
  Fix: While an ongoing issue, try to define explicit `yaml.schemas` associations for multi-document files. If possible, consider splitting complex multi-document files into single-document files, or using a tool like `yaml-schema-router` for more robust content-based schema routing.
• gotcha Configuring schema associations using `yaml.schemas` with glob patterns can be complex, especially when using local schema files. Paths must be relative to the project root, and overlapping globs can lead to unexpected behavior or incorrect schema application.
  Fix: Ensure local schema paths are correctly specified relative to your project root. Use specific glob patterns to avoid conflicts. Leverage `yaml.schemaStore.enable` and `yaml.kubernetesCRDStore.enable` for automatically managed schemas where applicable, or consider an external schema router for advanced scenarios.

Install

• npm install yaml-language-server npm
• yarn add yaml-language-server yarn
• pnpm add yaml-language-server pnpm

Imports

• Settings

  import { Settings } from 'yaml-language-server';

  Interface defining the configuration settings for the YAML language server, often used by clients to manage server behavior. Direct imports are primarily for type definitions when building custom tools or extensions that interact deeply with its internal settings structure.
• YAML_SCHEMA_ASSOCIATIONS

  import { YAML_SCHEMA_ASSOCIATIONS } from 'yaml-language-server';

  A constant or type definition related to how YAML files are associated with specific schemas. Useful for advanced configurations or client-side schema management within an LSP integration.
• ISchemaAssociations

  import { ISchemaAssociations } from 'yaml-language-server';

  An interface representing the structure for defining schema associations, enabling custom mappings between YAML file patterns and their corresponding JSON Schemas. Intended for programmatic setup of schema handling.

Quickstart

This quickstart demonstrates how to programmatically start and interact with the YAML Language Server as a child process using Node.js, establishing an LSP connection over standard I/O, sending an 'initialize' request, and notifying the server about a new document opening.

import { spawn } from 'child_process';
import { createConnection, MessageConnection, InitializeParams, TextDocumentItem, DidOpenTextDocumentParams } from 'vscode-languageserver/node';
import { TextDocuments } from 'vscode-languageserver-textdocument';

const serverPath = require.resolve('yaml-language-server/bin/yaml-language-server');

async function startYamlLanguageServer() {
    console.log(`Starting YAML Language Server from: ${serverPath}`);
    const serverProcess = spawn('node', [serverPath, '--stdio']);

    serverProcess.stdout.pipe(process.stdout);
    serverProcess.stderr.pipe(process.stderr);
    process.stdin.pipe(serverProcess.stdin);

    const connection: MessageConnection = createConnection(
        serverProcess.stdin,
        serverProcess.stdout
    );

    connection.listen();

    connection.onInitialize(async (params: InitializeParams) => {
        console.log('LSP Client: Initializing...');
        return {
            capabilities: {
                textDocumentSync: 1, // Full
                completionProvider: { resolveProvider: false, triggerCharacters: ['-', ':'] },
                hoverProvider: true,
                documentFormattingProvider: true,
                documentRangeFormattingProvider: true,
                documentSymbolProvider: true,
                workspace: { workspaceFolders: { supported: true } }
            },
            serverInfo: { name: 'yaml-language-client', version: '1.0' }
        };
    });

    // Send initialize request after connection is established
    connection.sendRequest('initialize', {
        processId: process.pid,
        rootUri: null,
        capabilities: {},
        workspaceFolders: null
    } as InitializeParams).then(async () => {
        console.log('LSP Client: Initialized. Sending didOpen notification...');
        // Example: Open a dummy YAML document
        const dummyYamlContent = `---
apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
    - name: my-container
      image: busybox
      command: ['sh', '-c', 'echo Hello Kubernetes! && sleep 3600']
`;

        const textDocument: TextDocumentItem = {
            uri: 'file:///tmp/test.yaml',
            languageId: 'yaml',
            version: 1,
            text: dummyYamlContent
        };
        connection.sendNotification('textDocument/didOpen', { textDocument } as DidOpenTextDocumentParams);
        console.log('LSP Client: Sent didOpen for test.yaml. Check server logs for activity.');
    }).catch(error => {
        console.error('LSP Client: Initialization failed:', error);
    });

    process.on('exit', () => {
        serverProcess.kill();
    });
}

startYamlLanguageServer().catch(console.error);