# Spectral — Flexible JSON and OpenAPI Linter

> Spectral is a JSON/YAML linter by Stoplight with built-in support for OpenAPI and AsyncAPI specifications, letting you enforce API design standards with custom or community rulesets.

## Install

Save in your project root:

# Spectral — Flexible JSON and OpenAPI Linter

## Quick Use
```bash
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml
# Lints your OpenAPI spec against the default ruleset
```

## Introduction
Spectral is an open-source JSON and YAML linter created by Stoplight. It ships with rulesets for OpenAPI v2/v3/v3.1, AsyncAPI, and Arazzo specifications, but can lint any JSON or YAML file against custom rules you define using JSONPath expressions.

## What Spectral Does
- Lints OpenAPI, AsyncAPI, and Arazzo specification files against built-in best-practice rules
- Supports custom rulesets defined in YAML or JavaScript for any JSON/YAML document format
- Uses JSONPath-plus expressions to target specific parts of a document for validation
- Reports issues with severity levels (error, warning, info, hint) and exact line/column locations
- Integrates into CI pipelines, editors (VS Code extension), and API design tools

## Architecture Overview
Spectral loads a ruleset (built-in or custom), parses the target document as a JSON tree, and evaluates each rule by resolving its JSONPath selector against the tree. Rules can use built-in functions (truthy, pattern, length, schema) or custom JavaScript functions for complex validation logic. Results are collected with document location info and formatted by the chosen output reporter.

## Self-Hosting & Configuration
- Install the CLI: npm install -g @stoplight/spectral-cli
- Create a .spectral.yaml in your project root to extend or override the default ruleset
- Extend built-in rulesets: extends: spectral:oas or spectral:asyncapi
- Define custom rules with given (JSONPath), then (function + options), and severity
- Run in CI: spectral lint openapi.yaml --fail-severity warn

## Key Features
- Built-in rulesets for OpenAPI v2, v3, v3.1, AsyncAPI v2/v3, and Arazzo v1.0
- Custom rules using JSONPath selectors and composable validation functions
- Over 20 built-in functions: truthy, falsy, pattern, enumeration, schema, length, and more
- VS Code extension for real-time linting as you edit API specs
- Multiple output formats: stylish (default), JSON, JUnit, HTML, and custom formatters

## Comparison with Similar Tools
- **Redocly CLI** — OpenAPI linting with bundling and preview; Spectral offers more flexible custom rules via JSONPath
- **openapi-generator validate** — Basic validation only; Spectral provides style and best-practice enforcement beyond schema correctness
- **Swagger Editor** — Visual editor with inline validation; Spectral is a CLI tool for CI integration and automation
- **Vacuum** — High-performance OpenAPI linter in Go; Spectral has a larger rule ecosystem and JavaScript extensibility

## FAQ
**Q: Can I lint non-OpenAPI files with Spectral?**
A: Yes. Spectral can lint any JSON or YAML file. Write custom rulesets with JSONPath selectors targeting your document structure.

**Q: How do I create a custom rule?**
A: Define a rule in .spectral.yaml with a description, given (JSONPath selector), then (validation function and options), and severity. Custom JavaScript functions can be loaded for complex logic.

**Q: Does Spectral validate the OpenAPI schema itself?**
A: Spectral focuses on style and best-practice rules beyond basic schema validation. For strict schema correctness, combine it with a JSON Schema validator.

**Q: Can I share rulesets across teams?**
A: Yes. Publish your ruleset as an npm package or host it at a URL. Other projects extend it with extends: ['@your-org/spectral-rules'] in their .spectral.yaml.

## Sources
- https://github.com/stoplightio/spectral
- https://docs.stoplight.io/docs/spectral

---
Source: https://tokrepo.com/en/workflows/asset-f637f00c
Author: AI Open Source