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 ${CLAUDESKILLDIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDESKILLDIR}/reports/schema-validation.json - Machine-readable validation findings with severity${CLAUDESKILLDIR}/reports/schema-validation.md - Human-readable report with fix recommendations${CLAUDESKILLDIR}/reports/breaking-changes.md - Breaking change analysis between schema versions${CLAUDESKILLDIR}/.spectral.yaml - Custom Spectral linting rule configuration
