Index of every page on this site: llms.txt
All skills
jeremylongshore avatar

/validating-api-schemas

@820dfc8
Run it yourself

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".

Use this Skill: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/validating-api-schemas

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈60 tokens for metadata: the name and description. ≈1.2k when used: this file. ≈2k more on demand in 3 files.

Description uses 3.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈241 characters, or 3.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.
  5. Check for security scheme coverage: every endpoint either declares a security requirement or is explicitly marked as public with rationale.
  6. Detect breaking changes by comparing the current schema against the previous released version: removed endpoints, removed required fields, type changes, and narrowed enum values.
  7. 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.
  8. Generate a validation report with severity levels (error, warning, info) and specific file:line references for each finding.

See 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
  • ${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 Handling

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 references/errors.md for comprehensive error patterns.

Examples

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 references/examples.md for additional examples.

Resources

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts2mo3 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill provides safe tools and instructions for validating API schemas against standard specifications like OpenAPI and GraphQL. It includes well-documented scripts and configurations for linting, structural validation, and breaking change detection using standard industry tools.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 820dfc8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 20 hours ago.

Activeupdated last month
What it can do
Reads files Edits files Runs commands
version
1.25.0
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
[
  "api",
  "graphql",
  "validating-api"
]
All 6 allowed tools
ReadWriteEditGrepGlobBash(api:schema-*)
Other metadata
compatibility
Designed for Claude Code

README badge

README badge for jeremylongshore/tons-of-skills-marketplace/validating-api-schemas