yaml-schema-lint

1.1.1 verified Fri May 01 auth: no javascript

A CLI tool to lint YAML files against JSON schemas using the yaml-language-server programmatic API. It validates syntax and schema compliance, loading schemas from a VS Code-style settings file and automatically from schemastore.org. Version 1.1.1 is current, with a release cadence of occasional updates. Key differentiators include: uses the same schema resolution logic as VS Code, supports custom tags, caching of Schema Store catalog, and multiple output formats (GitLab CodeQuality, JSON). Requires Node.js >=20.

Common errors

error Error: Cannot find module 'yaml-language-server' ↓

cause Missing peer dependency yaml-language-server; not included automatically.

fix

Install yaml-language-server explicitly: npm install yaml-language-server

error Error: No schema found for file path/to/file.yml ↓

cause The file does not match any schema mapping in settings file, Schema Store, or modeline.

fix

Add a schema mapping in your .vscode/settings.json under yaml.schemas, or use a modeline comment in the YAML file.

error Error: ENOENT: no such file or directory, open '.vscode/settings.json' ↓

cause Default settings file does not exist at .vscode/settings.json.

fix

Create a settings file or specify a custom path with --settings-path.

error Error: Invalid settings file: must be a JSON object ↓

cause The settings file is not valid JSON or is an array.

fix

Ensure the file is a JSON object (wrapped in { }), e.g., { "yaml.schemas": {} }.

Warnings

breaking v1.0.0 changed default behavior to fail on warnings (exits with non-zero when warnings are found). ↓

fix Use --no-fail-on-warnings to restore previous behavior.

gotcha Glob patterns must be quoted to prevent shell expansion (e.g., '**/*.yml' not **/*.yml). ↓

fix Always quote glob patterns in shell commands.

deprecated The --github-annotations option was removed in v0.2.0-beta.2. ↓

fix Use --output-file to generate GitHub Annotations via JSON output and a custom action.

gotcha Schema Store catalog caching uses default TTL of 24h; stale schemas may cause false positives/negatives. ↓

fix Set --cache-ttl to 0 (or a lower value) to disable caching, or clear the cache directory manually.

gotcha If no files match the pattern, the tool exits with an error by default (since v1.0.0). ↓

fix Use --no-fail-on-no-files to exit successfully with no matches.

Install

npm install yaml-schema-lint

yarn add yaml-schema-lint

pnpm add yaml-schema-lint

Imports

lint
wrong
```
const lint = require('yaml-schema-lint')
```
correct
```
import { lint } from 'yaml-schema-lint'
```
CLI tool primarily used from command line, but this is the programmatic API entry point.

YamlSchemaLintOptions

wrong

const { YamlSchemaLintOptions } = require('yaml-schema-lint')

correct

import type { YamlSchemaLintOptions } from 'yaml-schema-lint'

TypeScript type-only import for options interface.

default

wrong

const yamlSchemaLint = require('yaml-schema-lint').default

correct

import yamlSchemaLint from 'yaml-schema-lint'

ESM default export available since v1.0.0.

Quickstart

Shows both CLI usage and programmatic API with all options.

// Install globally or locally
// npm install --global yaml-schema-lint

// Command line usage:
// yaml-schema-lint '**/*.yml' --settings-path .vscode/settings.json

// Programmatic usage (ESM):
import { lint } from 'yaml-schema-lint';

const results = await lint({
  patterns: ['**/*.yml'],
  settingsPath: '.vscode/settings.json',
  noSchemaStore: false,
  cacheDir: '.cache/yaml-schema-lint',
  cacheTTL: 86400,
  format: 'gitlab-codequality',
  ignore: '**/node_modules/**',
  failOnWarnings: true,
  failOnNoFiles: true,
  debug: false,
});

console.log(results);
// Returns an object with { diagnostics, summary }