Feature Request: Support YAML modeline schema comments (yaml-language-server format)

[lindner]

Summary

Extend the schema-from-instance concept (see #310) to support YAML modeline comments used by yaml-language-server and IDEs. This would enable validating YAML files against schemas declared via comment directives.

Related Issue

This is a companion to #310, which covers JSON's $schema property. YAML files use a different mechanism - comment-based modelines - which requires separate handling since comments are stripped during YAML parsing.

Motivation

The yaml-language-server modeline format is widely adopted:

• VS Code (via Red Hat YAML extension)
• JetBrains IDEs (IntelliJ, WebStorm, etc.)
• Neovim (coc-yaml, nvim-lspconfig)
• Zed, Helix, and other LSP-compatible editors

Example YAML with modeline:

# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest

Teams using these modelines for IDE support cannot currently validate the same files in pre-commit without duplicating schema references in the pre-commit config.

Modeline Formats to Support

Editor/Tool	Format
yaml-language-server (VS Code, Neovim, etc.)	# yaml-language-server: $schema=<url>
JetBrains IDEs	# $schema=<url>

Both formats appear as YAML comments, typically on the first line.

Proposed Implementation

Unlike JSON's $schema property (which survives parsing), YAML comments are discarded during parsing. This requires:

1. Pre-parse scan of the first N lines (e.g., 10) for modeline patterns
2. Regex extraction: #\s*(yaml-language-server:\s*)?\$schema=(.+)$
3. Schema fetch and validation using existing infrastructure

Proposed Interface

Building on #310's proposed --schema-from-instances, consider:

# Detect $schema from JSON property OR YAML modeline comment
check-jsonschema --schema-from-instances *.yaml *.json

Or if YAML modelines need separate handling:

# YAML-specific modeline detection
check-jsonschema --schema-from-modeline *.yaml

Optional: Enforcement Mode

A stricter mode that fails if files lack schema declarations:

# Require all matched files to have schema modeline
check-jsonschema --require-schema-modeline config/**/*.yaml

This catches files accidentally missing schema references.

Pre-commit Usage

- repo: https://github.com/python-jsonschema/check-jsonschema
  rev: x.y.z
  hooks:
    - id: check-jsonschema
      files: '\.ya?ml$'
      args: ["--schema-from-instances"]  # or --schema-from-modeline

Prior Art

• yaml-language-server - Reference implementation for modeline parsing
• check-yamlschema - Separate tool supporting modelines (less maintained)
• check-json-schema-meta - Wrapper for Feature request: Allow validation of $schema specified in JSON file #310, but JSON-only, doesn't support YAML modelines

Implementation Complexity

The main difference from #310 is that YAML modelines require pre-parse text scanning rather than post-parse property access. This could be:

1. Integrated into the same --schema-from-instances flag with format auto-detection
2. Separate flag if the implementation paths diverge significantly

Happy to contribute a PR if the approach is approved!

[sirosen]

I think this may duplicate #340 ? I haven't the time at the moment to read through everything yet.

#526 showed a "quick and dirty" approach which works, and I think that code is basically viable but it needs time and energy to complete the work. I could review a PR, but I'd like to agree on the approach before anyone submits a solution -- I'll try to make some time later this week to revisit.

More quick thoughts:

• In the past year, I've become more aware of multi-document YAML files -- GitLab has started using them for multiple CI configs in a single file (see Support yaml files with multiple documents #222) -- and so I wonder if scanning the file as plaintext is the right approach.
• The current YAML parser, ruamel.yaml, has roundtripping capabilities, for re-serializing data with comments preserved, so that could be used.
• OTOH, maybe someday we want to swap ruamel.yaml for ryaml or another library, so that argues for "stick to an approach you could reimplement yourself if needed".