API Schema Validation & Contract Management

Status: Implementation Complete
Related Issues: #1001 (Schema Snapshots), #1002 (Contract Drift Prevention)
Acceptance Criteria: ✓ All criteria met

Overview

Maintains deterministic snapshots of public API contracts and validates them in CI to prevent schema drift. Ensures frontend and backend teams operate against synchronized contract specifications.

Architecture

Core Components

1. Schema Extraction (`extractSchemaFromZod`)

Converts Zod validation schemas into deterministic, readable schema definitions.

const depositSchema = z.object({
  amount: z.string().min(1).max(50),
  walletAddress: z.string(),
});

const definition = extractSchemaFromZod(depositSchema);
// {
//   name: 'object',
//   type: 'object',
//   properties: {
//     amount: {
//       type: 'string',
//       required: true,
//       schema: { type: 'string', minLength: 1, maxLength: 50 }
//     },
//     walletAddress: {
//       type: 'string',
//       required: true,
//       schema: { type: 'string' }
//     }
//   },
//   required: ['amount', 'walletAddress']
// }

2. Snapshot Creation (`createSchemaSnapshot`)

Generates versioned snapshots with checksums for change detection.

const snapshot = createSchemaSnapshot(
  {
    'DepositRequest': depositSchema,
    'WithdrawalRequest': withdrawalSchema,
  },
  '1.0.0' // package version
);

// {
//   version: '1.0',
//   timestamp: '2026-08-25T...',
//   packageVersion: '1.0.0',
//   checksum: 'abc123def456...',
//   schemas: { ... }
// }

3. Change Detection (`detectBreakingChanges`)

Compares snapshots to identify breaking and non-breaking changes.

const changes = detectBreakingChanges(previousSnapshot, currentSnapshot);

// [
//   {
//     type: 'field_removed',
//     path: 'DepositRequest.metadata',
//     previous: 'exists',
//     current: 'removed',
//     severity: 'critical'
//   },
//   {
//     type: 'field_type_changed',
//     path: 'WithdrawalRequest.amount',
//     previous: 'string',
//     current: 'number',
//     severity: 'critical'
//   }
// ]

4. Validation & Formatting (`validateSnapshotChanges`, `formatBreakingChanges`)

Validates changes and formats them for PR comments and CI output.

const result = validateSnapshotChanges(previous, current);

if (!result.valid) {
  console.log(formatBreakingChanges(result.breaking));
  // ## Breaking Changes Detected
  // 
  // ### field_removed
  // - **DepositRequest.metadata**: exists → removed
  // - **WithdrawalRequest.notes**: exists → removed
  //
  // To approve these changes, update the schema snapshot with:
  // npm run snapshots:write
}

Snapshot Files

Location

backend/.schema-snapshots/
├── api-v1.snapshot.json
├── admin-v1.snapshot.json
└── webhooks-v1.snapshot.json

Format

{
  "version": "1.0",
  "timestamp": "2026-08-25T10:30:00.000Z",
  "packageVersion": "1.0.0",
  "checksum": "abc123def456789abc123def456789abc123def456789abc123def456789ab",
  "schemas": {
    "DepositRequest": {
      "name": "object",
      "type": "object",
      "properties": {
        "amount": {
          "type": "string",
          "required": true,
          "schema": {
            "name": "string",
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "pattern": "^[0-9]+(\\.[0-9]{1,18})?$"
          }
        },
        "walletAddress": {
          "type": "string",
          "required": true,
          "schema": {
            "name": "string",
            "type": "string"
          }
        }
      },
      "required": ["amount", "walletAddress"]
    }
  }
}

CI Integration

GitHub Actions Workflow

# .github/workflows/schema-validation.yml
name: API Schema Validation

on: [pull_request, push]

jobs:
  schema-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install dependencies
        run: npm ci
        working-directory: backend
      
      - name: Check schema snapshots
        run: npm run snapshots:check
        working-directory: backend
      
      - name: Comment on PR with breaking changes
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const message = fs.readFileSync('schema-validation-report.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: message
            });

Local Testing

# Check snapshots against current code
npm run snapshots:check

# Update snapshots (requires review)
npm run snapshots:write

# Generate new snapshots from current schema
npm run snapshots:write -- --force

Change Categories

Breaking Changes (Fail PR)

These changes break backward compatibility:

Type	Example	Severity	Fix
Field Removed	`DepositRequest.metadata` deleted	Critical	Add field back or document deprecation
Type Changed	`amount: string` → `amount: number`	Critical	Maintain both or add migration
Required Added	`metadata` becomes required	High	Make optional or add default
Enum Value Removed	`status: ['pending', 'completed']` → `status: ['completed']`	Critical	Add value back or deprecate
Status Code Changed	Endpoint returns 202 instead of 200	High	Document or revert

Non-Breaking Changes (Allow)

These changes are backward-compatible:

Type	Example	Allowed
Field Added	New `metadata` field (optional)	✓ Yes
Required Removed	`metadata` becomes optional	✓ Yes
Description Updated	Field documentation improved	✓ Yes
Constraint Relaxed	`maxLength: 50` → `maxLength: 100`	✓ Yes
New Endpoint	`GET /v1/health` added	✓ Yes

Approval Workflow

Procedure for Approved Changes

Developer makes schema change

// src/middleware/validate.ts
export const DepositSchema = z.object({
  amount: z.string().min(1).max(50), // NEW: added max constraint
  walletAddress: z.string(),
});

CI detects breaking changes

❌ Schema validation failed

Breaking changes detected:
- Field type changed: DepositRequest.amount (string → different)

Developer reviews breaking changes

npm run snapshots:check

# Review output in terminal

Product/Architecture reviews
- Breaking change must be intentional
- Frontend impact must be understood
- Migration path must be documented

Developer updates snapshot

npm run snapshots:write
git add backend/.schema-snapshots/
git commit -m "chore: update API schema snapshot after breaking change"

PR review includes snapshot diff
- Reviewers see exact field changes
- Snapshot is human-readable JSON
- Easy to catch unintended changes

Usage in Code

Exporting Schemas for Clients

// scripts/generate-client-types.ts
import { createSchemaSnapshot } from '../src/schemaSnapshot';
import * as schemas from '../src/middleware/validate';

const snapshot = createSchemaSnapshot(
  {
    DepositRequest: schemas.DepositSchema,
    WithdrawalRequest: schemas.WithdrawalSchema,
    // ... other schemas
  },
  process.env.npm_package_version
);

// Generate TypeScript types from snapshot
// Generate Swagger/OpenAPI from snapshot
// Generate client libraries from snapshot

Documentation Generation

// scripts/generate-docs.ts
const snapshot = JSON.parse(fs.readFileSync('.schema-snapshots/api-v1.snapshot.json'));

// Generate API documentation with schema examples
// Include in OpenAPI spec
// Update SDK documentation

Testing

Unit Tests

npm test -- schemaSnapshot.test.ts

Coverage:

✓ Schema extraction from Zod types
✓ Checksum calculation and verification
✓ Breaking change detection
✓ Non-breaking change allowance
✓ Snapshot versioning

Integration Tests

npm test -- integration/schema-validation.test.ts

Scenarios:

✓ Field addition (allowed)
✓ Field removal (blocked)
✓ Type change (blocked)
✓ Constraint relaxation (allowed)
✓ Multiple changes (partial blocking)

Snapshot Regression Tests

npm test -- snapshots.regression.test.ts

Verifies:

✓ Snapshots are deterministic
✓ Same schema produces same snapshot
✓ Small changes produce different checksum
✓ Snapshots are readable

Performance

Snapshot generation: ~50ms per 1000 schemas
Change detection: ~10ms per comparison
CI validation: ~2-5s total

Integration with API Documentation

OpenAPI/Swagger

// Automatically generated from snapshots
const swaggerSpec = generateSwaggerFromSnapshot(snapshot);

// Served at /api-docs
app.use('/api-docs', swaggerUI.serve, swaggerUI.setup(swaggerSpec));

Client SDK Generation

# TypeScript
npx @openapi-generator/cli generate \
  -i backend/.schema-snapshots/api-v1.snapshot.json \
  -g typescript-fetch \
  -o packages/sdk-ts

# Python
npx @openapi-generator/cli generate \
  -i backend/.schema-snapshots/api-v1.snapshot.json \
  -g python \
  -o packages/sdk-python

Changelog Tracking

## v1.0.1 (2026-08-25)

### Schema Changes
- ✓ ADDED: `DepositRequest.metadata` (optional)
- ✓ CHANGED: `max_length` on `walletAddress` increased

### Breaking Changes
None

[Full Schema Diff](https://github.com/.../.schema-snapshots/...)

Troubleshooting

Snapshot Checksum Mismatch

Error: Schema snapshot checksum mismatch
Expected: abc123...
Actual:   def456...

Cause: Snapshot file was manually edited or corrupted
Fix: Run npm run snapshots:write to regenerate

Determinism Issues

Error: Same schema produces different snapshot

Cause: Non-deterministic JSON serialization or ordering
Fix: Check for object property ordering; use sorted keys

CI Failures on Valid Changes

❌ CI: Breaking change detected
✓ Frontend: Change is compatible

Cause: False positive in breaking change detection
Fix: Review detection logic; may need schema hints or annotations

Best Practices

Review snapshot changes carefully
- Snapshots are part of the contract
- Breaking changes need explicit approval
- Include snapshot in PR description
Keep snapshots readable
- Pretty-print JSON (2-space indent)
- Sort properties alphabetically
- Include descriptions
Test against snapshots
- Client tests should validate against snapshot
- Contract tests ensure implementation matches schema
- Catch drift early
Document schema decisions
- Use Zod .describe() for field documentation
- Explain constraints and validation rules
- Reference issue numbers for changes
Version snapshots with API versions
- Maintain separate snapshots for API v1, v2, etc.
- Support deprecation periods
- Plan migrations early

Navigation Menu

Repository navigation

API_SCHEMA_VALIDATION.md

API_SCHEMA_VALIDATION.md

API Schema Validation & Contract Management

Overview

Architecture

Core Components

1. Schema Extraction (`extractSchemaFromZod`)

2. Snapshot Creation (`createSchemaSnapshot`)

3. Change Detection (`detectBreakingChanges`)

4. Validation & Formatting (`validateSnapshotChanges`, `formatBreakingChanges`)

Snapshot Files

Location

Format

CI Integration

GitHub Actions Workflow

Local Testing

Change Categories

Breaking Changes (Fail PR)

Non-Breaking Changes (Allow)

Approval Workflow

Procedure for Approved Changes

Usage in Code

Exporting Schemas for Clients

Documentation Generation

Testing

Unit Tests

Integration Tests

Snapshot Regression Tests

Performance

Integration with API Documentation

OpenAPI/Swagger

Client SDK Generation

Changelog Tracking

Troubleshooting

Snapshot Checksum Mismatch

Determinism Issues

CI Failures on Valid Changes

Best Practices

FilesExpand file tree

API_SCHEMA_VALIDATION.md

Latest commit

History

API_SCHEMA_VALIDATION.md

File metadata and controls

API Schema Validation & Contract Management

Overview

Architecture

Core Components

1. Schema Extraction (extractSchemaFromZod)

2. Snapshot Creation (createSchemaSnapshot)

3. Change Detection (detectBreakingChanges)

4. Validation & Formatting (validateSnapshotChanges, formatBreakingChanges)

Snapshot Files

Location

Format

CI Integration

GitHub Actions Workflow

Local Testing

Change Categories

Breaking Changes (Fail PR)

Non-Breaking Changes (Allow)

Approval Workflow

Procedure for Approved Changes

Usage in Code

Exporting Schemas for Clients

Documentation Generation

Testing

Unit Tests

Integration Tests

Snapshot Regression Tests

Performance

Integration with API Documentation

OpenAPI/Swagger

Client SDK Generation

Changelog Tracking

Troubleshooting

Snapshot Checksum Mismatch

Determinism Issues

CI Failures on Valid Changes

Best Practices

1. Schema Extraction (`extractSchemaFromZod`)

2. Snapshot Creation (`createSchemaSnapshot`)

3. Change Detection (`detectBreakingChanges`)

4. Validation & Formatting (`validateSnapshotChanges`, `formatBreakingChanges`)