API Contract Validator skill
Validates API responses against OpenAPI, JSON Schema, and consumer-driven contracts to prevent breaking changes and ensure backward compatibility.
- GitHub stars
- 248
- Files
- 1
- Last commit
- Nov 3, 2026
- License
- MIT
- Allowed tools
- —
What does the API Contract Validator skill do?
API Contract Validator validates API responses against OpenAPI, JSON Schema, and consumer-driven contracts to prevent breaking changes and ensure backward compatibility.
Summary generated from the skill's SKILL.md.
About the API Contract Validator skill
Ensuring API responses match their documentation is what the API Contract Validator does for QA engineers and developers. This skill helps prevent breaking changes by verifying that every response field, status code, and header aligns perfectly with the authoritative source of truth. It is designed for teams that need to maintain backward compatibility and ensure that provider updates do not disrupt consumer expectations.
An agent should load this skill when tasked with writing, reviewing, or planning API contract tests. It utilizes OpenAPI specifications, JSON Schema definitions, and consumer-driven contracts to perform deep validation. The skill produces structured test suites that check for schema drift, type changes, and removed properties. It relies on tools and frameworks like Ajv for schema validation and can be integrated into workflows using Playwright, Postman, or Rest-Assured across various programming languages including TypeScript, Python, and Java.
What an agent can do with it
- 1Verify OpenAPI complianceCheck that a specific API endpoint returns a response body that matches the defined OpenAPI 3.x specification.
- 2Detect breaking changesIdentify if a new schema version has removed required fields or changed data types in a way that breaks existing consumers.
- 3Implement consumer-driven testingEnsure that the API provider meets the actual requirements and expectations of its consumers through contract testing.
- 4Validate error response formatsConfirm that error responses follow the standard structure and include the necessary error message fields.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the API Contract Validator skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the API Contract Validator skill in Claude Code
~/.claude/skills/API-Contract-Validator/SKILL.md
$ npx degit PramodDutta/qaskills/seed-skills/api-contract-validator ~/.claude/skills/API-Contract-ValidatorInstall the API Contract Validator skill in Claude Code (project)
.claude/skills/API-Contract-Validator/SKILL.md
$ npx degit PramodDutta/qaskills/seed-skills/api-contract-validator .claude/skills/API-Contract-ValidatorInstall the API Contract Validator skill in Codex
~/.agents/skills/API-Contract-Validator/SKILL.md
$ npx degit PramodDutta/qaskills/seed-skills/api-contract-validator ~/.agents/skills/API-Contract-ValidatorInstall the API Contract Validator skill in Gemini CLI
~/.gemini/skills/API-Contract-Validator/SKILL.md
$ npx degit PramodDutta/qaskills/seed-skills/api-contract-validator ~/.gemini/skills/API-Contract-ValidatorInstall the API Contract Validator skill in Claude.ai
npx degit PramodDutta/qaskills/seed-skills/api-contract-validator API-Contract-Validator && zip -r API-Contract-Validator.zip API-Contract-Validator # claude.ai → Customize → Skills → + → Create skill → Upload a skill → API-Contract-Validator.zip
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepramoddutta/qaskills/seed-skills/api-contract-validator is public and reachablegithub.com/pramoddutta/qaskills/tree/HEAD/seed-skills/api-co ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-03github.com/pramoddutta/qaskills/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/pramoddutta/qaskills/blob/HEAD/seed-skills/api-co ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/pramoddutta/qaskills/blob/HEAD/seed-skills/api-co ↗Pass
- SKILL.md follows the Agent Skills formatname "API Contract Validator" is not 1-64 lowercase letters, digits and single hyphensgithub.com/pramoddutta/qaskills/blob/HEAD/seed-skills/api-co ↗Finding
SKILL.md
View on GitHubAPI Contract Validator Skill
You are an expert QA engineer specializing in API contract validation. When the user asks you to write, review, or plan API contract tests, follow these detailed instructions to systematically verify that API responses conform to their published specifications, that backward compatibility is maintained across versions, and that consumer expectations are always met.
Core Principles
- Contract as source of truth -- The OpenAPI specification or JSON Schema definition is the authoritative contract between API provider and consumer. Every response field, status code, and header must match the spec exactly, not approximately.
- Backward compatibility by default -- New API versions must not remove existing fields, change field types, or alter response structures without explicit versioning. Additive changes are safe; subtractive changes break consumers.
- Consumer-driven validation -- Contracts should reflect what consumers actually use, not just what the provider documents. Consumer-driven contract testing ensures that provider changes do not break real consumer expectations.
- Schema-first development -- Define the contract before writing implementation code. This ensures that tests validate intent rather than implementation, and that multiple teams can develop in parallel against a shared specification.
- Fail fast on drift -- Contract validation must run in CI on every commit. The longer a contract violation goes undetected, the more consumers it affects and the harder it is to fix.
- Version everything -- API versions, schema versions, and contract versions must be explicitly tracked. Tests should validate that the correct version is served and that version negotiation works correctly.
- Validate the complete response -- Do not validate only the happy-path response body. Validate status codes, headers, content types, error response formats, pagination structures, and edge cases like empty collections.
Project Structure
tests/
contracts/
openapi/
validate-responses.spec.ts # Validate responses against OpenAPI spec
validate-request.spec.ts # Validate request schemas
backward-compat.spec.ts # Backward compatibility checks
json-schema/
schema-validation.spec.ts # JSON Schema validation tests
schema-evolution.spec.ts # Schema change detection
consumer-driven/
consumer-contracts.spec.ts # Consumer-driven contract tests
pact-provider.spec.ts # Pact provider verification
graphql/
schema-validation.spec.ts # GraphQL schema validation
breaking-changes.spec.ts # GraphQL breaking change detection
fixtures/
api-client.ts # Typed API client helper
schema-loader.ts # Load and parse OpenAPI specs
contract-helpers.ts # Contract validation utilities
specs/
openapi.yaml # OpenAPI 3.x specification
schemas/ # JSON Schema definitions
user.schema.json
document.schema.json
error.schema.json
playwright.config.ts
Configuration
// tests/contracts/fixtures/schema-loader.ts
import * as fs from 'fs';
import * as path from 'path';
import * as yaml from 'js-yaml';
export interface OpenAPISpec {
openapi: string;
info: { title: string; version: string };
paths: Record<string, Record<string, PathOperation>>;
components: { schemas: Record<string, JSONSchema> };
}
export interface PathOperation {
operationId: string;
summary?: string;
parameters?: ParameterObject[];
requestBody?: RequestBodyObject;
responses: Record<string, ResponseObject>;
}
export interface JSONSchema {
type?: string;
properties?: Record<string, JSONSchema>;
required?: string[];
items?: JSONSchema;
enum?: unknown[];
format?: string;
minimum?: number;
maximum?: number;
minLength?: number;
maxLength?: number;
pattern?: string;
additionalProperties?: boolean | JSONSchema;
}
interface ParameterObject {
name: string;
in: string;
required?: boolean;
schema: JSONSchema;
}
interface RequestBodyObject {
required?: boolean;
content: Record<string, { schema: JSONSchema }>;
}
interface ResponseObject {
description: string;
content?: Record<string, { schema: JSONSchema }>;
headers?: Record<string, { schema: JSONSchema }>;
}
export function loadOpenAPISpec(specPath: string): OpenAPISpec {
const content = fs.readFileSync(specPath, 'utf-8');
if (specPath.endsWith('.yaml') || specPath.endsWith('.yml')) {
return yaml.load(content) as OpenAPISpec;
}
return JSON.parse(content);
}
export function loadJSONSchema(schemaPath: string): JSONSchema {
const content = fs.readFileSync(schemaPath, 'utf-8');
return JSON.parse(content);
}
export function getResponseSchema(
spec: OpenAPISpec,
path: string,
method: string,
statusCode: string
): JSONSchema | null {
const pathObj = spec.paths[path];
if (!pathObj) return null;
const operation = pathObj[method.toLowerCase()];
if (!operation) return null;
const response = operation.responses[statusCode] || operation.responses['default'];
if (!response?.content) return null;
const jsonContent = response.content['application/json'];
return jsonContent?.schema || null;
}
// tests/contracts/fixtures/contract-helpers.ts
import Ajv, { ErrorObject } from 'ajv';
import addFormats from 'ajv-formats';
import { JSONSchema } from './schema-loader';
const ajv = new Ajv({ allErrors: true, strict: false });
addFormats(ajv);
export interface ValidationResult {
valid: boolean;
errors: ErrorObject[] | null;
summary: string;
}
export function validateAgainstSchema(
data: unknown,
schema: JSONSchema
): ValidationResult {
const validate = ajv.compile(schema);
const valid = validate(data) as boolean;
return {
valid,
errors: validate.errors || null,
summary: valid
? 'Response matches schema'
: `Schema violations: ${(validate.errors || [])
.map((e) => `${e.instancePath} ${e.message}`)
.join('; ')}`,
};
}
export function checkBackwardCompatibility(
oldSchema: JSONSchema,
newSchema: JSONSchema
): { compatible: boolean; breakingChanges: string[] } {
const breakingChanges: string[] = [];
// Check for removed required fields
const oldRequired = new Set(oldSchema.required || []);
const newRequired = new Set(newSchema.required || []);
const oldProperties = oldSchema.properties || {};
const newProperties = newSchema.properties || {};
// Removed properties that were in old schema
for (const prop of Object.keys(oldProperties)) {
if (!(prop in newProperties)) {
breakingChanges.push(`Removed property: "${prop}"`);
}
}
// Type changes on existing properties
for (const [prop, oldPropSchema] of Object.entries(oldProperties)) {
if (prop in newProperties) {
const newPropSchema = newProperties[prop];
if (oldPropSchema.type !== newPropSchema.type) {
breakingChanges.push(
`Type changed for "${prop}": ${oldPropSchema.type} -> ${newPropSchema.type}`
);
}
}
}
// New required fields (breaking for existing consumers)
for (const field of newRequired) {
if (!oldRequired.has(field)) {
breakingChanges.push(`New required field added: "${field}"`);
}
}
// Enum value removal
for (const [prop, oldPropSchema] of Object.entries(oldProperties)) {
if (prop in newProperties && oldPropSchema.enum && newProperties[prop].enum) {
const removedValues = oldPropSchema.enum.filter(
(v) => !newProperties[prop].enum!.includes(v)
);
if (removedValues.length > 0) {
breakingChanges.push(
`Enum values removed from "${prop}": ${removedValues.join(', ')}`
);
}
}
}
return {
compatible: breakingChanges.length === 0,
breakingChanges,
};
}
OpenAPI Response Validation
// tests/contracts/openapi/validate-responses.spec.ts
import { test, expect } from '@playwright/test';
import { loadOpenAPISpec, getResponseSchema } from '../fixtures/schema-loader';
import { validateAgainstSchema } from '../fixtures/contract-helpers';
import * as path from 'path';
const spec = loadOpenAPISpec(path.resolve(__dirname, '../specs/openapi.yaml'));
test.describe('OpenAPI Response Validation', () => {
test('GET /api/users returns response matching spec', async ({ request }) => {
const response = await request.get('/api/users');
const status = response.status().toString();
const body = await response.json();
const schema = getResponseSchema(spec, '/api/users', 'get', status);
expect(schema, `No schema found for GET /api/users ${status}`).not.toBeNull();
const result = validateAgainstSchema(body, schema!);
expect(result.valid, result.summary).toBe(true);
});
test('GET /api/users/:id returns response matching spec', async ({ request }) => {
const response = await request.get('/api/users/1');
const status = response.status().toString();
const body = await response.json();
const schema = getResponseSchema(spec, '/api/users/{id}', 'get', status);
expect(schema).not.toBeNull();
const result = validateAgainstSchema(body, schema!);
expect(result.valid, result.summary).toBe(true);
});
test('POST /api/users error response matches error schema', async ({ request }) => {
// Send invalid data to trigger validation error
const response = await request.post('/api/users', {
data: { invalid: 'payload' },
});
const status = response.status().toString();
const body = await response.json();
const schema = getResponseSchema(spec, '/api/users', 'post', status);
if (schema) {
const result = validateAgainstSchema(body, schema);
expect(result.valid, result.summary).toBe(true);
}
// Verify standard error format
expect(body).toHaveProperty('error');
expect(typeof body.error).toBe('object');
if (body.error) {
expect(body.error).toHaveProperty('message');
expect(typeof body.error.message).toBe('string');
}
});
test('response content-type matches spec', async ({ request }) => {
const response = await request.get('/api/users');
const contentType = response.headers()['content-type'];
expect(contentType).toContain('application/json');
});
test('pagination response structure matches spec', async ({ request }) => {
const response = await request.get('/api/users?page=1&limit=10');
const body = await response.json();
// Standard pagination contract
expect(body).toHaveProperty('data');
expect(Array.isArray(body.data)).toBe(true);
expect(body).toHaveProperty('pagination');
expect(body.pagination).toHaveProperty('page');
expect(body.pagination).toHaveProperty('limit');
expect(body.pagination).toHaveProperty('total');
expect(body.pagination).toHaveProperty('totalPages');
expect(typeof body.pagination.page).toBe('number');
expect(typeof body.pagination.limit).toBe('number');
expect(typeof body.pagination.total).toBe('number');
expect(typeof body.pagination.totalPages).toBe('number');
});
test('validate all documented endpoints return conforming responses', async ({ request }) => {
const violations: string[] = [];
for (const [pathTemplate, pathObj] of Object.entries(spec.paths)) {
for (const [method, operation] of Object.entries(pathObj)) {
if (['get'].includes(method)) {
// Replace path parameters with test values
const resolvedPath = pathTemplate.replace(/{(\w+)}/g, '1');
try {
const response = await request.get(resolvedPath);
const status = response.status().toString();
const body = await response.json().catch(() => null);
if (body) {
const schema = getResponseSchema(spec, pathTemplate, method, status);
if (schema) {
const result = validateAgainstSchema(body, schema);
if (!result.valid) {
violations.push(
`${method.toUpperCase()} ${pathTemplate} (${status}): ${result.summary}`
);
}
}
}
} catch (error) {
// Skip unreachable endpoints
}
}
}
}
expect(
violations,
`Contract violations found:\n${violations.join('\n')}`
).toHaveLength(0);
});
});
JSON Schema Validation
// tests/contracts/json-schema/schema-validation.spec.ts
import { test, expect } from '@playwright/test';
import { loadJSONSchema } from '../fixtures/schema-loader';
import { validateAgainstSchema } from '../fixtures/contract-helpers';
import * as path from 'path';
const userSchema = loadJSONSchema(
path.resolve(__dirname, '../specs/schemas/user.schema.json')
);
const errorSchema = loadJSONSchema(
path.resolve(__dirname, '../specs/schemas/error.schema.json')
);
test.describe('JSON Schema Validation', () => {
test('user object conforms to user schema', async ({ request }) => {
const response = await request.get('/api/users/1');
expect(response.status()).toBe(200);
const user = await response.json();
const result = validateAgainstSchema(user, userSchema);
expect(result.valid, result.summary).toBe(true);
});
test('user list items all conform to user schema', async ({ request }) => {
const response = await request.get('/api/users');
expect(response.status()).toBe(200);
const body = await response.json();
const users = body.data || body;
for (let i = 0; i < users.length; i++) {
const result = validateAgainstSchema(users[i], userSchema);
expect(result.valid, `User at index ${i}: ${result.summary}`).toBe(true);
}
});
test('error responses conform to error schema', async ({ request }) => {
const response = await request.get('/api/users/nonexistent-id');
if (response.status() >= 400) {
const error = await response.json();
const result = validateAgainstSchema(error, errorSchema);
expect(result.valid, result.summary).toBe(true);
}
});
test('required fields are always present', async ({ request }) => {
const response = await request.get('/api/users/1');
const user = await response.json();
const requiredFields = userSchema.required || [];
for (const field of requiredFields) {
expect(
user,
`Required field "${field}" is missing from user response`
).toHaveProperty(field);
}
});
test('field types match schema definitions', async ({ request }) => {
const response = await request.get('/api/users/1');
const user = await response.json();
const properties = userSchema.properties || {};
for (const [field, fieldSchema] of Object.entries(properties)) {
if (user[field] !== undefined && user[field] !== null) {
switch (fieldSchema.type) {
case 'string':
expect(typeof user[field], `${field} should be string`).toBe('string');
break;
case 'number':
case 'integer':
expect(typeof user[field], `${field} should be number`).toBe('number');
break;
case 'boolean':
expect(typeof user[field], `${field} should be boolean`).toBe('boolean');
break;
case 'array':
expect(Array.isArray(user[field]), `${field} should be array`).toBe(true);
break;
case 'object':
expect(typeof user[field], `${field} should be object`).toBe('object');
break;
}
}
}
});
test('string format constraints are enforced', async ({ request }) => {
const response = await request.get('/api/users/1');
const user = await response.json();
const properties = userSchema.properties || {};
for (const [field, fieldSchema] of Object.entries(properties)) {
if (user[field] && fieldSchema.type === 'string') {
if (fieldSchema.format === 'email') {
expect(user[field]).toMatch(/^[^\s@]+@[^\s@]+\.[^\s@]+$/);
}
if (fieldSchema.format === 'date-time') {
expect(new Date(user[field]).toISOString()).toBeTruthy();
}
if (fieldSchema.format === 'uri') {
expect(() => new URL(user[field])).not.toThrow();
}
if (fieldSchema.minLength) {
expect(user[field].length).toBeGreaterThanOrEqual(fieldSchema.minLength);
}
if (fieldSchema.maxLength) {
expect(user[field].length).toBeLessThanOrEqual(fieldSchema.maxLength);
}
}
}
});
});
Backward Compatibility Testing
// tests/contracts/openapi/backward-compat.spec.ts
import { test, expect } from '@playwright/test';
import { loadOpenAPISpec } from '../fixtures/schema-loader';
import { checkBackwardCompatibility } from '../fixtures/contract-helpers';
import * as path from 'path';
test.describe('Backward Compatibility', () => {
test('current schema is backward compatible with previous version', () => {
const previousSpec = loadOpenAPISpec(
path.resolve(__dirname, '../specs/openapi-v1.yaml')
);
const currentSpec = loadOpenAPISpec(
path.resolve(__dirname, '../specs/openapi.yaml')
);
const schemasToCheck = ['User', 'Document', 'Error'];
for (const schemaName of schemasToCheck) {
const oldSchema = previousSpec.components.schemas[schemaName];
const newSchema = currentSpec.components.schemas[schemaName];
if (oldSchema && newSchema) {
const result = checkBackwardCompatibility(oldSchema, newSchema);
expect(
result.compatible,
`Breaking changes in ${schemaName}:\n${result.breakingChanges.join('\n')}`
).toBe(true);
}
}
});
test('API version header is present and correct', async ({ request }) => {
const response = await request.get('/api/users');
const apiVersion = response.headers()['api-version'] ||
response.headers()['x-api-version'];
expect(apiVersion).toBeDefined();
expect(apiVersion).toMatch(/^\d+\.\d+\.\d+$/);
});
test('deprecated fields still present but marked', async ({ request }) => {
const response = await request.get('/api/users/1');
const body = await response.json();
// If deprecated fields exist, they should still be present for backward compat
const spec = loadOpenAPISpec(path.resolve(__dirname, '../specs/openapi.yaml'));
const userSchema = spec.components.schemas['User'];
if (userSchema?.properties) {
for (const [field, fieldSchema] of Object.entries(userSchema.properties)) {
if ((fieldSchema as Record<string, unknown>).deprecated) {
// Deprecated fields should still be in the response
expect(
body,
`Deprecated field "${field}" removed before deprecation period ended`
).toHaveProperty(field);
}
}
}
});
test('new required fields are not added without version bump', async ({ request }) => {
const v1Response = await request.get('/api/v1/users/1');
const v2Response = await request.get('/api/v2/users/1');
if (v1Response.status() === 200 && v2Response.status() === 200) {
const v1Body = await v1Response.json();
const v2Body = await v2Response.json();
const v1Fields = new Set(Object.keys(v1Body));
const v2Fields = new Set(Object.keys(v2Body));
// All v1 fields must still exist in v2
for (const field of v1Fields) {
expect(
v2Fields.has(field),
`Field "${field}" from v1 is missing in v2`
).toBe(true);
}
}
});
});
Files in this skill
1API Contract Validator skill questions
How do I install the API Contract Validator skill in Claude Code?
Run npx degit PramodDutta/qaskills/seed-skills/api-contract-validator ~/.claude/skills/API-Contract-Validator. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the API Contract Validator skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How does the tool prevent breaking changes?
It checks for removed properties, type changes on existing properties, new required fields, and removed enum values between schema versions.
What specifications can be used for validation?
The skill supports OpenAPI/Swagger specifications, JSON Schema definitions, and consumer-driven contracts.
Does it validate more than just the response body?
Yes, it validates status codes, headers, content types, error response formats, pagination structures, and edge cases.