Help us improve
Share bugs, ideas, or general feedback.
From jaan-to
Validates OpenAPI/Swagger contracts through a multi-tool pipeline: Spectral linting, oasdiff breaking change detection, Prism mocking, and Schemathesis fuzzing. Use when verifying API spec compliance.
npx claudepluginhub parhumm/jaan-to --plugin jaan-toHow this skill is triggered — by the user, by Claude, or both
Slash command
/jaan-to:qa-contract-validate [openapi-spec-path] [--baseline baseline-spec] [--url api-url][openapi-spec-path] [--baseline baseline-spec] [--url api-url]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Validate API contracts through a multi-tool pipeline -- lint, diff, mock, and fuzz.
Enables consumer-driven contract testing with Pact, allowing each consumer to publish expected API shapes and providers to verify against them in CI.
Checks and configures API contract testing with Pact for consumer-provider agreements, OpenAPI spec validation, and schema testing. Use for CI breaking change detection and compliance checks.
Checks and configures API contract testing with Pact for consumer-provider agreements, OpenAPI validation, and schema testing. Supports JS/Python projects with --check-only, --fix options.
Share bugs, ideas, or general feedback.
Validate API contracts through a multi-tool pipeline -- lint, diff, mock, and fuzz.
$JAAN_CONTEXT_DIR/tech.md - Tech stack context$JAAN_LEARN_DIR/jaan-to-qa-contract-validate.learn.md - Past lessons (loaded in Pre-Execution)$JAAN_TEMPLATES_DIR/jaan-to-qa-contract-validate.template.md - Output template${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocolContract Source: $ARGUMENTS
Input modes:
Scope: OpenAPI/Swagger specs only (v1). GraphQL schema validation and gRPC proto linting are out of scope.
MANDATORY -- Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md
Skill name: qa-contract-validate
Execute: Step 0 (Init Guard) -> A (Load Lessons) -> B (Resolve Template) -> C (Offer Template Seeding)
Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md
Override field for this skill: language_qa-contract-validate
ultrathink
Use extended reasoning for:
openapi: or swagger: version fieldCheck each tool using only commands permitted by allowed-tools. Use npx --no-install for npm tools to prevent silent auto-installation. Never use bare npx or which.
| Tool | Check Command | Type |
|---|---|---|
| Spectral | npx --no-install @stoplight/spectral-cli --version | npm |
| oasdiff | oasdiff --version | Go binary (NOT npm) |
| Prism | npx --no-install @stoplight/prism-cli --version | npm |
| Schemathesis | schemathesis --version | Python pip |
Report availability:
TOOL AVAILABILITY
-------------------------------------------------------------
Spectral: {available/unavailable}
oasdiff: {available/unavailable} (requires --baseline)
Prism: {available/unavailable} (requires --url)
Schemathesis: {available/unavailable} (requires --url)
Pipeline: {count}/4 tools available
Hard rule: If 0 out of 4 tools are available, report status as INCONCLUSIVE (not PASS). Output must state: "No validation tools installed -- contract compliance unknown. Install at least one tool to validate."
Based on available tools and provided inputs:
| Tool | Condition | Stage |
|---|---|---|
| Spectral | Always (if available) | Lint spec |
| oasdiff | If --baseline provided AND tool available | Breaking changes |
| Prism | If --url provided AND tool available | Conformance check |
| Schemathesis | If --url provided AND tool available | Fuzz testing |
CONTRACT VALIDATION PLAN
-------------------------------------------------------------
Spec: {spec_path} ({endpoint_count} endpoints, {schema_count} schemas)
Baseline: {baseline_path or "none"}
API URL: {url or "none"}
Pipeline Stages:
1. Spectral Lint: {will run / skipped (unavailable)}
2. oasdiff Diff: {will run / skipped (no baseline or unavailable)}
3. Prism Conformance: {will run / skipped (no URL or unavailable)}
4. Schemathesis Fuzz: {will run / skipped (no URL or unavailable)}
Output Folder: $JAAN_OUTPUTS_DIR/qa/contract-validate/{id}-{slug}/
Use AskUserQuestion:
Do NOT proceed to Phase 2 without explicit approval.
Parallel Tool Execution: Spectral, oasdiff, Prism, and Schemathesis are independent with no data dependencies between them. When multiple tools are available, execute them concurrently (e.g., parallel Bash calls or Task-based sub-agents) and aggregate results after all complete.
Incremental Validation: When --baseline is provided, use oasdiff to identify changed endpoints first. Then scope Schemathesis fuzzing to only those endpoints using --endpoint filter, avoiding full-spec fuzzing on unchanged paths.
Schemathesis Speed Tuning: For large specs, constrain fuzzing with --workers=4 --max-examples=50 --stateful=links to bound execution time while maintaining coverage quality.
Reference: See
${CLAUDE_PLUGIN_ROOT}/docs/extending/qa-contract-validate-reference.mdsection "Performance Optimization" for parallel execution patterns and Schemathesis tuning options.
npx @stoplight/spectral-cli lint {spec_path} --format json --ruleset .spectral.yaml
If .spectral.yaml not found, use built-in rulesets. Parse JSON output:
oasdiff breaking --fail-on ERR {baseline_path} {spec_path} --format json
oasdiff is a Go binary, NOT npm. Install: go install github.com/tufin/oasdiff@latest or brew install oasdiff.
CI: use oasdiff/oasdiff-action@{pinned-sha} GitHub Action (pin to immutable commit SHA, never @latest).
Parse output: list breaking changes with severity and path.
npx @stoplight/prism-cli proxy {spec_path} --host 0.0.0.0 --port 4010
Or validate against running API in proxy mode. Parse conformance violations.
schemathesis run --url {api_url} {spec_path} --stateful=links --format json
schemathesis is a Python pip package, NOT npm. Parse: test count, failure count, defect details.
Combine all tool outputs into aggregate status:
| Stage | Status | Findings |
|---|---|---|
| Spectral | PASS/WARN/FAIL | {error_count} errors, {warn_count} warnings |
| oasdiff | PASS/FAIL/SKIPPED | {breaking_count} breaking changes |
| Prism | PASS/FAIL/SKIPPED | {violation_count} conformance violations |
| Schemathesis | PASS/FAIL/SKIPPED | {defect_count} defects found |
Aggregate: PASS (all ran pass), WARN (warnings only), FAIL (any errors/breaking/defects), INCONCLUSIVE (0 tools ran).
source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/id-generator.sh"
SUBDOMAIN_DIR="$JAAN_OUTPUTS_DIR/qa/contract-validate"
mkdir -p "$SUBDOMAIN_DIR"
NEXT_ID=$(generate_next_id "$SUBDOMAIN_DIR")
Template:
API contract validation for {spec_title} v{spec_version} ({endpoint_count} endpoints).
Pipeline: {tools_ran}/{tools_total} tools executed. Aggregate status: {PASS/WARN/FAIL/INCONCLUSIVE}.
Spectral: {status}. oasdiff: {status}. Prism: {status}. Schemathesis: {status}.
Path: $JAAN_OUTPUTS_DIR/qa/contract-validate/${NEXT_ID}-${slug}/
Files:
{id}-{slug}.md -- Main validation reportspectral-results.json -- Raw Spectral output (if ran)oasdiff-results.json -- Raw oasdiff output (if ran)schemathesis-results.json -- Raw Schemathesis output (if ran)source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/index-updater.sh"
add_to_index \
"$SUBDOMAIN_DIR/README.md" \
"$NEXT_ID" \
"${NEXT_ID}-${slug}" \
"{Spec Title} Contract Validation" \
"{Executive Summary}"
Use AskUserQuestion:
If "Learn from this": Run /jaan-to:learn-add qa-contract-validate "{feedback}"
$JAAN_OUTPUTS_DIR path