yaml-schema-lint

Lint YAML files against JSON schemas using the yaml-language-server programmatic API. Validates syntax and schema compliance, with schemas loaded from a settings file and schemastore.org.

Installation

npm install --global yaml-schema-lint

Usage

yaml-schema-lint [options] <patterns...>

Arguments

Argument	Description
<patterns...>	One or more YAML file paths or glob patterns. Quote globs to prevent shell expansion (e.g. '**/*.yml').

Options

Option	Default	Description
--settings-path <path>	.vscode/settings.json	Path to a JSON settings file containing yaml.schemas and yaml.customTags.
--no-schema-store	(enabled)	Disable fetching schemas from schemastore.org.
--cache-dir <path>	.cache/yaml-schema-lint	Directory for caching the Schema Store catalog.
--cache-ttl <seconds>	86400 (24h)	How long the cached Schema Store catalog is considered fresh.
--format <name>	gitlab-codequality	Output file format when --output-file is used (gitlab-codequality, json).
--output-file <path>	(none)	Write an additional report file in the chosen format.
--ignore <patterns>	**/node_modules/**	Comma-separated glob patterns to exclude from file matching.
--no-fail-on-warnings	(disabled)	Do not exit with an error when only warnings are found.
--no-fail-on-no-files	(disabled)	Exit successfully when no files match the patterns.
--debug	false	Enable debug logging.

Examples

yaml-schema-lint '**/*.yml' '**/*.yaml'
yaml-schema-lint --settings-path custom/settings.json '**/*.yml'
yaml-schema-lint --no-schema-store '**/*.yml'
yaml-schema-lint --ignore 'dist/**,build/**' '**/*.yml'
yaml-schema-lint '**/*.yml' --output-file gl-codequality.json

Schema resolution

Schemas are resolved from three sources, in order of priority:

1. Settings file -- The yaml.schemas property maps schema URIs to file glob patterns. Custom YAML tags can be defined via yaml.customTags.

   {
     "yaml.schemas": {
       "https://json.schemastore.org/gitlab-ci": [".gitlab-ci.yml", "gitlab/*.yml"]
     },
     "yaml.customTags": ["!reference sequence"]
   }
   

2. Schema Store -- YAML-relevant schemas are automatically fetched from schemastore.org and matched against file names. The catalog is cached locally (default: .cache/yaml-schema-lint/schemastore-catalog.json) with a configurable TTL. Disable with --no-schema-store.

3. Modeline comments -- Inline schema declarations in YAML files are supported natively by the language server:

   # yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
   name: CI
   on: push
   

Output

By default, human-readable diagnostics are printed to the console with colorized severity and summary:

Report files

When --output-file is provided, an additional report file is written in the format selected by --format. The console output still runs.

gitlab-codequality

Produces a JSON array conforming to the GitLab Code Quality report format

Severity mapping:

yaml-language-server	GitLab Code Quality
Error	major
Warning	minor
Information	info
Hint	info

json

Produces a JSON array of per-file results with 1-based line/column numbers and string severity values. This format is consumed by the GitHub Action to create Check Runs.

Severity mapping:

yaml-language-server	JSON
Error	error
Warning	warning
Information	information
Hint	hint

Exit codes

Code	Meaning
0	All files passed with no errors or warnings, or --no-fail-on-warnings is set and no errors were found, or no files matched with --no-fail-on-no-files.
1	At least one error or warning was found (default), no files matched (default), or a fatal error occurred.

CI integration

GitLab CI

yaml-lint:
  stage: validate
  image: node:24-slim
  script:
    - npx yaml-schema-lint '**/*.yml' --format gitlab-codequality --output-file gl-codequality.json
  artifacts:
    reports:
      codequality: gl-codequality.json

GitHub Actions

The yaml-schema-lint-action runs yaml-schema-lint and creates a GitHub Check with inline annotations and a markdown summary:

yaml-lint:
  runs-on: ubuntu-latest
  permissions:
    contents: read
    checks: write
    pull-requests: read
  steps:
    - uses: actions/checkout@v4

    - uses: X-Guardian/yaml-schema-lint-action@v1
      with:
        patterns: "'**/*.yml' '**/*.yaml'"

See the action README for all available inputs.

License

MIT