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

Start by reviewing related issue #310 and the existing schema-from-instances infrastructure. Determine how YAML input is parsed and where CLI options are defined, then implement the agreed modeline behavior. Done means supported modeline formats can provide a schema for YAML validation without duplicating schema references.

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 #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!