home / skills / jeremylongshore / claude-code-plugins-plus-skills / validating-api-schemas

validating-api-schemas skill

/plugins/api-development/api-schema-validator/skills/validating-api-schemas

This skill validates API schemas against OpenAPI, JSON Schema, and GraphQL specifications to ensure contracts meet standards.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill validating-api-schemas

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.4 KB

---
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.0.0
author: Jeremy Longshore <[email protected]>
license: MIT
---

# Validating Api Schemas

## Overview


This skill provides automated assistance for api schema validator tasks.
This skill provides automated assistance for the described functionality.

## Prerequisites

Before using this skill, ensure you have:
- API design specifications or requirements documented
- Development environment with necessary frameworks installed
- Database or backend services accessible for integration
- Authentication and authorization strategies defined
- Testing tools and environments configured

## Instructions

1. Use Read tool to examine existing API specifications from {baseDir}/api-specs/
2. Define resource models, endpoints, and HTTP methods
3. Document request/response schemas and data types
4. Identify authentication and authorization requirements
5. Plan error handling and validation strategies
1. Generate boilerplate code using Bash(api:schema-*) with framework scaffolding
2. Implement endpoint handlers with business logic
3. Add input validation and schema enforcement
4. Integrate authentication and authorization middleware
5. Configure database connections and ORM models
1. Write integration tests covering all endpoints


See `{baseDir}/references/implementation.md` for detailed implementation guide.

## Output

- `{baseDir}/src/routes/` - Endpoint route definitions
- `{baseDir}/src/controllers/` - Business logic handlers
- `{baseDir}/src/models/` - Data models and schemas
- `{baseDir}/src/middleware/` - Authentication, validation, logging
- `{baseDir}/src/config/` - Configuration and environment variables
- OpenAPI 3.0 specification with complete endpoint definitions

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources

- Express.js and Fastify for Node.js APIs
- Flask and FastAPI for Python APIs
- Spring Boot for Java APIs
- Gin and Echo for Go APIs
- OpenAPI Specification 3.0+ for API documentation

Overview

This skill validates API schemas and contracts against OpenAPI, JSON Schema, and GraphQL specifications. It helps catch structural issues, type mismatches, and missing documentation before runtime. Use it to enforce consistent API design and reduce integration errors across teams.

How this skill works

The skill parses supplied API definitions and runs them through spec-aware validators for OpenAPI 3.x, JSON Schema draft versions, and GraphQL SDL. It reports schema errors, missing components, invalid types, incompatible responses, and security definition gaps. It can also suggest fixes and generate a prioritized list of failing checks to guide remediation.

When to use it

During API design reviews to validate OpenAPI or GraphQL drafts
Before CI pipelines to block merges with schema regressions
When onboarding integrations to verify contract compatibility
As part of automated linting for schema repositories
Prior to generating server or client code from specs

Best practices

Keep schemas single-source-of-truth and validate them in CI for every change
Adopt a consistent JSON Schema draft and document it in the repo
Include explicit response schemas and example payloads for each endpoint
Validate security schemes and required scopes alongside types
Run schema validation early in the development cycle to avoid downstream rework

Example use cases

Fail CI builds when an OpenAPI file introduces a breaking type change
Lint a GraphQL SDL for missing type definitions and nullable mismatches
Validate generated client models against canonical JSON Schema before release
Audit security definitions to ensure OAuth2 scopes are declared where required
Produce a remediation checklist for a legacy API migration to OpenAPI 3.x

FAQ

Which specification versions are supported?

OpenAPI 3.x, common JSON Schema drafts, and standard GraphQL SDL are supported; confirm exact drafts with your integration settings.

Can this run in CI pipelines?

Yes. Integrate the validator step into CI to fail builds on schema errors and emit machine-readable reports for developers.