Validating API Schemas

Overview

Validate API specifications against OpenAPI 3.0/3.1, JSON Schema Draft 2020-12, and GraphQL SDL standards using linting rules, structural analysis, and best-practice enforcement. Detect incomplete schemas, undocumented endpoints, inconsistent naming conventions, and breaking changes before they reach consumers.

Prerequisites

• OpenAPI specification files (YAML or JSON) or GraphQL SDL schema files
• Schema linting tool: Spectral (OpenAPI), graphql-schema-linter (GraphQL), or ajv-cli (JSON Schema)
• Version control for schema files to enable diff-based breaking change detection
• CI pipeline for automated schema validation on every pull request
• oasdiff or openapi-diff for breaking change detection between versions

Instructions

1. Locate all API specification files using Glob, identifying OpenAPI specs, JSON Schema definitions, and GraphQL SDL files across the project.
2. Run structural validation to verify the specification conforms to the declared standard (OpenAPI 3.0, 3.1, or JSON Schema Draft 2020-12) and is syntactically valid.
3. Apply Spectral linting rules to enforce naming conventions (camelCase properties, kebab-case paths), required descriptions on all operations, and example values for request/response schemas.
4. Verify schema completeness: every endpoint has documented request schemas, all response status codes have schemas (including 400, 401, 404, 500), and all $ref references resolve.