feat: add official @eslint/yaml language plugin

[andreahlert]

Summary

This PR adds an RFC for creating an official ESLint language plugin for YAML, published as @eslint/yaml, under the ESLint organization.

Follow-up to Discussion #20482, where @nzakas welcomed an RFC to kickstart this effort.

Checklist

• New design in designs/2026-official-yaml-language-plugin/
• README.md follows the template
• All sections filled in

Links

• RFC document: designs/2026-official-yaml-language-plugin/README.md
• Discussion: Interest in an official @eslint/yaml plugin? #20482

[eslint-github-bot]

Hi @andreahlert!, thanks for the Pull Request

The pull request title isn't properly formatted. We ask that you update the pull request title to match this format, as we use it to generate changelogs and automate releases.

• The commit message tag wasn't recognized. Did you mean "docs", "fix", or "feat"?
• There should be a space following the initial tag and colon, for example 'feat: Message'.
• The first letter of the tag should be in lowercase

To Fix: You can fix this problem by clicking 'Edit' next to the pull request title at the top of this page.

Read more about contributing to ESLint here

[lumirlumir]

This looks like a good start! I've left a couple of comments.

[lumirlumir]

It seems to me that the YAML 1.1/1.2 selection option would be better placed under languageOptions rather than mode.

export type YAMLLanguageOptions = {
  parserOptions?: {
    defaultYAMLVersion?: "1.1" | "1.2";
  };
};

eslint-plugin-yml already implements it this way. However, there can be different opinions on it, so I’d like to raise it for further discussion.

[DMartens]

Maybe add it directly to languageOptions similar to ecmaVersion for JavaScript:

export type YAMLLanguageOptions = {
	yamlVersion?: "1.1" | "1.2"
}

[andreahlert]

The current approach follows the same pattern as @eslint/json (json/json, json/jsonc, json/json5) and @eslint/markdown (commonmark, gfm), where mode is a constructor param and separate language entries let users target different file sets declaratively. Open to either approach if the team prefers otherwise.

[andreahlert]

Interesting parallel with ecmaVersion. The trade-off is declarative per-glob targeting (current approach) vs. a single language with config override. Happy to go with whatever the team prefers.

[ota-meshi]

FYI, the YAML version can be changed using a directive in the YAML file:

%YAML 1.2
---

For this reason, I named it the defaultYAMLVersion option.

[fasttime]

I'm reading in the YAML 1.2.2 spec (emphasis mine):

A version 1.2 YAML [processor] must also accept [documents] with an explicit
"%YAML 1.1" directive.
Note that version 1.2 is mostly a superset of version 1.1, defined for the
purpose of ensuring JSON compatibility.
Hence a version 1.2 [processor] should process version 1.1 [documents] as if
they were version 1.2, giving a warning on points of incompatibility (handling
of [non-ASCII line breaks], as described [above]).

And in the YAML 1.1 spec:

Documents with a "YAML" directive specifying a higher minor version (e.g. "%YAML 1.2") should be processed with an appropriate warning.

That means, if I understand correctly, neither %YAML 1.1 nor %YAML 1.2 changes the way the document is parsed. It only instructs the parses to generate certain warnings?

[andreahlert]

@nzakas @mdjermanovic @alexzherdev any suggestions? I would like to start on this.

[DMartens]

In ideal circumstances we should base the plugin on the work done by ota-meshi:
Move the parser and source code to the official plugin @eslint/yaml and eslint-plugin-yml keeps the stylistic rules.

[andreahlert]

Using yaml-eslint-parser as a dependency (rather than moving the code) seems like a good middle ground. It leverages the mature parser without the overhead of transferring repos between orgs. Collaboration with @ota-meshi is definitely welcome, and the door is open for deeper integration down the road.

[fasttime]

In ESLint languages, comments are generally not represented as AST nodes. Instead, they are stored sequentially in separate structures (e.g., a comments array or token list) for convenience. This holds true for each of the js, json, css and html languages provided by official (or semi-official) plugins (markdown AFAIK doesn't have real comments.)

[nzakas]

Because @ota-meshi has already implemented a YAML language in eslint-plugin-yml, I think it's worth asking if it's worth creating another plugin that will do something similar.

The goal of having official plugins is to ensure 1) a consistent level of quality and 2) guaranteed ongoing maintenance. If eslint-plugin-yml already provides both, then it may be a better choice to support and promote it rather than creating a new plugin from scratch.

I'm curious what @andreahlert and @ota-meshi think, and if there are any differences in way eslint-plugin-yml and this RFC are approaching the same problems.