| name | validating-api-schemas |
| description | Validate API schemas against OpenAPI, JSON Schema, and GraphQL specifications.
Use when validating API schemas and contracts.
Trigger with phrases like "validate API schema", "check OpenAPI spec", or "verify schema".
|
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash(api:schema-*) |
| version | 1.24.0 |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| license | MIT |
| tags | ["api","graphql","validating-api"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
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
- Locate all API specification files using Glob, identifying OpenAPI specs, JSON Schema definitions, and GraphQL SDL files across the project.
- 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.
- 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.
- 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.
- Check for security scheme coverage: every endpoint either declares a security requirement or is explicitly marked as public with rationale.
- Detect breaking changes by comparing the current schema against the previous released version: removed endpoints, removed required fields, type changes, and narrowed enum values.
- Validate consistency across endpoints: pagination parameters use the same naming (
page/limit vs offset/count), error response envelopes follow a single standard, and date formats are consistent.
- Generate a validation report with severity levels (error, warning, info) and specific file:line references for each finding.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/reports/schema-validation.json - Machine-readable validation findings with severity${CLAUDE_SKILL_DIR}/reports/schema-validation.md - Human-readable report with fix recommendations
