The specification
Status: draft. The document below covers the whole format as implemented today, documented faithfully and without extension. It is a complete description. It is not yet a formal specification — it lacks normative wording and a conformance section, which is the roadmap.
The document currently lives in the repository, and is the single source of truth. Publishing it as a normative document on this site, section by section, is the first item of open work — and the reason it has not simply been copied here is that a specification should not exist in two places that can drift.
Read the full document The JSON Schema
What it covers
| Section | What it defines |
|---|---|
| Using the schema | Binding the schema in an editor and in CI |
| The Ruleset Object | The root object, its fields, and the rule that a ruleset must contribute something |
| Rules | The rule object, and what a rule name identifies |
given and path expressions |
How a rule selects the nodes it applies to |
then and functions |
What runs against a selected node, and how functions are invoked |
severity |
The severity values and how off behaves |
formats |
Restricting rules to document formats |
message |
Message templating and the available placeholders |
| Rule shorthands | The compact forms a rule may take |
extends |
Inheriting from other rulesets, and the tuple form |
aliases |
Named, reusable path expressions and scoped aliases |
overrides |
Per-file and per-location adjustment |
parserOptions |
Severities for problems in the document itself |
| Custom functions | Loading and invoking your own functions |
| Extension properties | The x- escape hatch |
| Conformance notes | Known implementation-defined behavior — the seed of a real conformance section |
| Versioning | How the schema is versioned today |
| Provenance and license | Where this came from, and under what terms |
What is deliberately not in it
No extensions. The document describes the format as it exists, not as it might be improved. Divergence from the format people already use would defeat the purpose — your existing rulesets are the thing being protected here.
No opinions about the linter. How an engine resolves references, caches, or reports results is implementation detail. Where the current text does record implementation-defined behavior, it does so explicitly in Conformance notes, which is where the formal conformance section will grow from.
How to argue with it
The most useful contribution is not a wording suggestion — it is a ruleset that behaves differently than this document says it should. That is a bug in the specification, and the file itself is the bug report.
Where the specification and the reference implementation disagree today, the implementation is right by definition and the document has to be corrected. This document was reverse engineered from that implementation’s internals, so those disagreements exist and finding them is the work.