spotlight-spec
A standalone, versioned specification of the Spotlight ruleset format — and an explorable catalog of every rule.
spotlight-spec defines the portable, serializable shape of a Spotlight (Spectral)
ruleset — the rules, extends, formats, functions,
and severities you put in a .yaml/.json file and hand to any conforming
linter. It is published as a single, self-contained JSON Schema (2020-12), derived
faithfully from Spectral's own internal meta-schemas and reconciled into one document, so the format is
documented and validatable independent of any single implementation.
Spotlight extends that baseline with its own first-class rule properties — tags (namespaced
classifiers), title (a display name), reference (a canonical docs URL), and
prompt (an AI fix instruction). They're detailed in the schema below.
Schema properties
The shape of a ruleset document, and of a single rule. Spotlight's own additions are highlighted.
Ruleset (top level)
| Property | Type | Description |
|---|---|---|
rules | object | Map of rule name → rule definition (or a severity to toggle a rule inherited via extends). |
extends | string · array | Inherit rules from other rulesets — e.g. spotlight:oas, spotlight:asyncapi, spotlight:arazzo. |
formats | array | Document formats the whole ruleset targets (e.g. oas3, asyncapi2). |
functions | array | Names of custom functions a rule's then may reference. |
functionsDir | string | Directory the custom functions are loaded from. |
overrides | array | Apply or re-scope rules to specific files / JSON Pointers. |
aliases | object | Reusable named JSONPath targets that a rule's given can reference. |
documentationUrl | string | Docs URL for the ruleset. |
description | string | Human description of the ruleset. |
Rule
| Property | Type | Description |
|---|---|---|
given | JSONPath · array | Where in the document the rule applies. |
then | object · array | The assertion — a field plus a function (with optional functionOptions). |
severity | error · warn · info · hint · off | How a violation is reported. Spotlight ships every rule at info — raise to warn/error to enforce. |
message | string | The lint message; supports |
description | string | What the rule checks, and why it matters. |
formats | array | Restrict the rule to specific document formats. |
recommended | boolean | Whether the rule runs in the ruleset's recommended set. |
resolved | boolean | Lint the resolved ($ref-dereferenced) document, or the raw source. |
documentationUrl | string | Per-rule documentation link. |
Spotlight extensions beyond Spectral
| Property | Type | Description |
|---|---|---|
tags | array | Namespaced classifiers tooling groups & filters by: format:<artifact>, spec:<location>, experience:<dimension>, topic:<feature>, owasp:<apiN>. |
title | string | A short Title Case display name (e.g. Response Define 429). |
reference | string (url) | Canonical documentation URL — every Spotlight rule points at its page on this site. |
prompt | string | A natural-language fix instruction an AI assistant (Claude, Gemini, ChatGPT) can apply to remediate a violation. |
Explore the rules
All 733 rules Spotlight applies, across 12 artifact types. Pick an artifact to browse and filter its rules, then open any rule for its full detail and AI fix prompt.