spectral-ruleset-authoringlisted

# Spectral Ruleset Authoring ## When to Use This Skill Use when setting up spec-linting governance for a new API program, when migrating from an ad-hoc review checklist to automated enforcement, or when adding a custom rule to catch a project-specific violation. ## 1. Rule Anatomy ```yaml rules: rule-id: message: "{{description}} — {{error}}" description: "Human-readable explanation of what the rule checks." severity: error # error | warn | info | hint given: "$.paths.*.*.responses" # JSONPath expression selecting nodes to check then: function: truthy # built-in or custom function ``` | Severity | CI behaviour | |---|---| | `error` | Non-zero exit — blocks merge | | `warn` | Logged, exit 0 — advisory | | `info` | Informational only | Use `error` only for violations that break consumers or contradict a hard house rule. Use `warn` for style preferences. ## 2. Recommended Baseline Ruleset ```yaml extends: ["spectral:oas"] rules: # Enforce RFC 9457 error media type problem-json-on-errors: message: "Error responses must use application/problem+json, not application/json." severity: error given: "$.paths.*.*.responses[?(@property >= '400')].content" then: function: schema functionOptions: schema: not: required: ["application/json"] # Require operationId on every operation operation-id-required: message: "Every operation must have an operationId." severity: