Spectral Ruleset

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://spectral.stoplight.io/schemas/ruleset",
  "title": "Spectral Ruleset",
  "description": "A Spectral ruleset configuration file defining API linting rules and extensions.",
  "type": "object",
  "properties": {
    "extends": {
      "oneOf": [
        { "type": "string" },
        { "type": "array", "items": { "type": "string" } }
      ],
      "description": "Ruleset(s) to extend. Accepts a string or array of npm package names or URLs."
    },
    "rules": {
      "type": "object",
      "description": "Map of rule names to rule definitions.",
      "additionalProperties": {
        "$ref": "#/$defs/Rule"
      }
    },
    "aliases": {
      "type": "object",
      "description": "Map of alias names to JSONPath expressions for reuse across rules.",
      "additionalProperties": {
        "oneOf": [
          { "type": "string" },
          { "type": "array", "items": { "type": "string" } }
        ]
      }
    },
    "overrides": {
      "type": "array",
      "description": "Override rule severities for specific file patterns.",
      "items": {
        "type": "object",
        "properties": {
          "files": {
            "type": "array",
            "items": { "type": "string" }
          },
          "rules": {
            "type": "object",
            "additionalProperties": {
              "oneOf": [
                { "type": "string", "enum": ["error", "warn", "info", "hint", "off"] },
                { "type": "integer", "minimum": 0, "maximum": 3 }
              ]
            }
          }
        },
        "required": ["files", "rules"]
      }
    },
    "formats": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Limit ruleset to specific document formats."
    }
  },
  "$defs": {
    "Rule": {
      "type": "object",
      "properties": {
        "description": {
          "type": "string",
          "description": "Human-readable description of what the rule enforces."
        },
        "message": {
          "type": "string",
          "description": "Message shown when the rule is violated. Supports {{error}} and {{path}} placeholders."
        },
        "severity": {
          "oneOf": [
            { "type": "string", "enum": ["error", "warn", "info", "hint", "off"] },
            { "type": "integer", "minimum": 0, "maximum": 3 }
          ],
          "description": "Severity level: error(0), warn(1), info(2), hint(3), or off."
        },
        "given": {
          "oneOf": [
            { "type": "string" },
            { "type": "array", "items": { "type": "string" } }
          ],
          "description": "JSONPath expression(s) selecting nodes to test."
        },
        "then": {
          "oneOf": [
            { "$ref": "#/$defs/Then" },
            { "type": "array", "items": { "$ref": "#/$defs/Then" } }
          ]
        },
        "formats": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Limit the rule to specific document formats."
        },
        "recommended": {
          "type": "boolean",
          "description": "Whether to include this rule in recommended mode."
        }
      },
      "required": ["given", "then"]
    },
    "Then": {
      "type": "object",
      "properties": {
        "field": {
          "type": "string",
          "description": "Optional sub-field to apply the function to."
        },
        "function": {
          "type": "string",
          "description": "Name of the Spectral function to apply (truthy, falsy, pattern, schema, enumeration, length, etc.)."
        },
        "functionOptions": {
          "type": "object",
          "description": "Options to pass to the function.",
          "additionalProperties": true
        }
      },
      "required": ["function"]
    }
  }
}