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".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill validating-api-schemasLoading…
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.
graphql-schema-linter (GraphQL), or ajv-cli (JSON Schema)oasdiff or openapi-diff for breaking change detection between versions$refpage/limit vs offset/count), error response envelopes follow a single standard, and date formats are consistent.See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
${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${CLAUDE_SKILL_DIR}/reports/breaking-changes.md - Breaking change analysis between schema versions${CLAUDE_SKILL_DIR}/.spectral.yaml - Custom Spectral linting rule configuration${CLAUDE_SKILL_DIR}/scripts/validate-schema.sh - CI-ready schema validation script${CLAUDE_SKILL_DIR}/reports/schema-coverage.md - Endpoint documentation completeness matrix| Error | Cause | Solution |
|---|---|---|
| Unresolved $ref | Schema references a component that does not exist or has a typo | List all $ref targets and verify each resolves; check for circular references |
| Missing response schema | Endpoint returns undocumented status codes | Add schemas for all observed response codes; use default response as fallback |
| Inconsistent naming | Mix of camelCase and snake_case property names across endpoints | Define naming convention in Spectral ruleset; apply auto-fix where possible |
| Breaking change detected | Required field added to existing request schema | Make new field optional with default value; or create new API version for breaking changes |
| Schema too permissive | Use of additionalProperties: true or missing type constraints | Set additionalProperties: false by default; require explicit type and format on all properties |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Pre-commit schema lint: Git pre-commit hook runs Spectral against all modified OpenAPI files, blocking commits that introduce undocumented endpoints, missing descriptions, or inconsistent naming.
Breaking change CI gate: On pull requests modifying API specs, oasdiff compares against the main branch version, failing the build if backward-incompatible changes are detected without a version bump.
Schema completeness audit: Generate a matrix showing every endpoint vs. documentation status (description, request schema, response schemas for 200/400/401/404/500, examples), highlighting gaps with coverage percentage.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Transcribe audio via OpenAI Audio Transcriptions API (Whisper).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.