{"id":26673,"library":"yaml-schema-lint","title":"yaml-schema-lint","description":"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.","status":"active","version":"1.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/X-Guardian/yaml-schema-lint","tags":["javascript","yaml","lint","linter","schema","json-schema","yaml-language-server","schemastore","ci"],"install":[{"cmd":"npm install yaml-schema-lint","lang":"bash","label":"npm"},{"cmd":"yarn add yaml-schema-lint","lang":"bash","label":"yarn"},{"cmd":"pnpm add yaml-schema-lint","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency used to parse YAML and validate against JSON schemas.","package":"yaml-language-server","optional":false}],"imports":[{"note":"CLI tool primarily used from command line, but this is the programmatic API entry point.","wrong":"const lint = require('yaml-schema-lint')","symbol":"lint","correct":"import { lint } from 'yaml-schema-lint'"},{"note":"TypeScript type-only import for options interface.","wrong":"const { YamlSchemaLintOptions } = require('yaml-schema-lint')","symbol":"YamlSchemaLintOptions","correct":"import type { YamlSchemaLintOptions } from 'yaml-schema-lint'"},{"note":"ESM default export available since v1.0.0.","wrong":"const yamlSchemaLint = require('yaml-schema-lint').default","symbol":"default","correct":"import yamlSchemaLint from 'yaml-schema-lint'"}],"quickstart":{"code":"// Install globally or locally\n// npm install --global yaml-schema-lint\n\n// Command line usage:\n// yaml-schema-lint '**/*.yml' --settings-path .vscode/settings.json\n\n// Programmatic usage (ESM):\nimport { lint } from 'yaml-schema-lint';\n\nconst results = await lint({\n  patterns: ['**/*.yml'],\n  settingsPath: '.vscode/settings.json',\n  noSchemaStore: false,\n  cacheDir: '.cache/yaml-schema-lint',\n  cacheTTL: 86400,\n  format: 'gitlab-codequality',\n  ignore: '**/node_modules/**',\n  failOnWarnings: true,\n  failOnNoFiles: true,\n  debug: false,\n});\n\nconsole.log(results);\n// Returns an object with { diagnostics, summary }","lang":"typescript","description":"Shows both CLI usage and programmatic API with all options."},"warnings":[{"fix":"Use --no-fail-on-warnings to restore previous behavior.","message":"v1.0.0 changed default behavior to fail on warnings (exits with non-zero when warnings are found).","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always quote glob patterns in shell commands.","message":"Glob patterns must be quoted to prevent shell expansion (e.g., '**/*.yml' not **/*.yml).","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use --output-file to generate GitHub Annotations via JSON output and a custom action.","message":"The --github-annotations option was removed in v0.2.0-beta.2.","severity":"deprecated","affected_versions":">=0.2.0-beta.2"},{"fix":"Set --cache-ttl to 0 (or a lower value) to disable caching, or clear the cache directory manually.","message":"Schema Store catalog caching uses default TTL of 24h; stale schemas may cause false positives/negatives.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use --no-fail-on-no-files to exit successfully with no matches.","message":"If no files match the pattern, the tool exits with an error by default (since v1.0.0).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install yaml-language-server explicitly: npm install yaml-language-server","cause":"Missing peer dependency yaml-language-server; not included automatically.","error":"Error: Cannot find module 'yaml-language-server'"},{"fix":"Add a schema mapping in your .vscode/settings.json under yaml.schemas, or use a modeline comment in the YAML file.","cause":"The file does not match any schema mapping in settings file, Schema Store, or modeline.","error":"Error: No schema found for file path/to/file.yml"},{"fix":"Create a settings file or specify a custom path with --settings-path.","cause":"Default settings file does not exist at .vscode/settings.json.","error":"Error: ENOENT: no such file or directory, open '.vscode/settings.json'"},{"fix":"Ensure the file is a JSON object (wrapped in { }), e.g., { \"yaml.schemas\": {} }.","cause":"The settings file is not valid JSON or is an array.","error":"Error: Invalid settings file: must be a JSON object"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}