validate-api-responses

name	validate-api-responses
description	Validate API responses against schemas
shortcut	val

Validate API Responses

Implement comprehensive API response validation using JSON Schema, OpenAPI specifications, and custom business rules to ensure data integrity and contract compliance.

When to Use This Command

Use /validate-api-responses when you need to:

• Ensure API responses conform to documented schemas
• Catch contract violations before they reach clients
• Validate response data types, formats, and constraints
• Implement runtime schema validation in production
• Create automated contract testing pipelines
• Monitor API compatibility across versions

DON'T use this when:

• Building prototypes without defined schemas (premature optimization)
• Working with highly dynamic responses (consider runtime type checking instead)
• Validating simple scalar responses (overkill for basic types)

Design Decisions

This command implements JSON Schema + Ajv as the primary approach because:

• Industry-standard schema format with wide ecosystem support
• Blazing fast validation with compiled schemas (10x faster than alternatives)
• Comprehensive format validators for dates, emails, UUIDs, etc.
• Custom keyword support for business-specific validation
• Clear, actionable error messages for debugging

Alternative considered: OpenAPI/Swagger validation

• Better for full API contract validation
• Includes request validation, not just responses
• More complex setup and configuration
• Recommended when using OpenAPI for documentation

Alternative considered: Joi/Yup validation

• More intuitive API for JavaScript developers
• Better TypeScript integration
• Limited to JavaScript ecosystem
• Recommended for Node.js-only projects

Prerequisites

Before running this command:

1. Define response schemas (JSON Schema or OpenAPI)
2. Identify validation points (middleware, tests, runtime)
3. Determine error handling strategy
4. Plan performance impact for large payloads
5. Consider validation modes (strict vs. permissive)

Implementation Process

Step 1: Define Response Schemas

Create JSON Schema definitions for all API responses with proper constraints.

Step 2: Configure Validation Middleware

Set up validation middleware to intercept and validate responses automatically.

Step 3: Implement Custom Validators

Add business-specific validation rules beyond structural validation.

Step 4: Set Up Error Handling

Configure how validation errors are reported to clients and logged.

Step 5: Create Test Suites

Build comprehensive test suites for schema validation and edge cases.

Output Format

The command generates:

• schemas/ - JSON Schema definitions for all endpoints
• validators/ - Compiled validator functions
• middleware/response-validator.js - Express/Koa middleware
• tests/schema-validation.test.js - Validation test suites
• docs/api-schemas.md - Human-readable schema documentation
• monitoring/validation-metrics.js - Validation failure tracking

Code Examples

Example 1: JSON Schema Validation with Ajv

// schemas/user-response.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "UserResponse",
  "type": "object",
  "required": ["id", "email", "createdAt"],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 255
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["admin", "user", "moderator"]
      },
      "minItems": 1,
      "uniqueItems": true
    },
    : {
      : ,
      : {
        : {
          : ,
          : [, , ]
        },
        : {
          : 
        }
      }
    },
    : {
      : ,
      : 
    },
    : {
      : ,
      : 
    }
  },
  : 
}


  = ();
 addFormats = ();
 fs = ();
 path = ();

  {
  () {
    . =  ({
      : ,
      : ,
      : ,
      : ,
      : 
    });

    
    (.);

    
    .();

    
    . = .();
    . = {};
  }

  () {
    
    ..({
      : ,
      : ,
      : () {
          () {
          (schemaValue) {
             :
               data. >  ().();
             :
               !data. && data.;
            :
               ;
          }
        };
      }
    });
  }

  () {
     schemaDir = path.(__dirname, );
     schemas = {};

    fs.(schemaDir).( {
       (file.()) {
         schema = .(
          fs.(path.(schemaDir, file), )
        );
        schemas[schema.] = schema;
        ..(schema);
      }
    });

     schemas;
  }

  () {
     (!.[schemaId]) {
       schema = .[schemaId];
       (!schema) {
          ();
      }
      .[schemaId] = ..(schema);
    }
     .[schemaId];
  }

  () {
     validator = .(schemaId);
     valid = (data);

     (!valid) {
       {
        : ,
        : .(validator.),
        : validator.
      };
    }

     { :  };
  }

  () {
     errors.( ({
      : err. || ,
      : err.,
      : err.,
      : err.,
      : err.
    }));
  }
}


  = ();

 () {
   validator =  ();
   {
    enabled = ,
    strict = ,
    logErrors = ,
    includeErrorDetails = process.. !== 
  } = options;

    () {
     (!enabled)  ();

    
     originalJson = res.;

    res. = () {
      
       schemaId = (req., res.);

       (schemaId) {
         result = validator.(schemaId, data);

         (!result.) {
           (logErrors) {
            .(, {
              : req.,
              : req.,
              schemaId,
              : result.
            });
          }

           (strict) {
            
             originalJson.(, {
              : ,
              : includeErrorDetails ? result. : 
            });
          }

          
          
        }
      }

       originalJson.(, data);
    };

    ();
  };
}

 () {
  
   schemaMap = {
    : ,
    : ,
    : ,
    : ,
    : 
  };

   routeKey = ;
   schemaMap[routeKey];
}

. = createResponseValidationMiddleware;

Example 2: OpenAPI Response Validation

// validators/openapi-validator.js
const OpenAPIValidator = require('express-openapi-validator');
const SwaggerParser = require('@apidevtools/swagger-parser');
const fs = require('fs');
const yaml = require('js-yaml');

class OpenAPIResponseValidator {
  constructor(specPath) {
    this.specPath = specPath;
    this.spec = null;
    this.middleware = null;
  }

  async initialize() {
    // Parse and validate OpenAPI spec
    this.spec = await SwaggerParser.validate(this.specPath);

    // Create validation middleware
    this.middleware = OpenAPIValidator.middleware({
      apiSpec: this.specPath,
      validateRequests: false,  // Only validate responses
      : {
        : ,
        : ,
        :  {
          .(, {
            : req.,
            : req.,
            : error.,
            : error.
          });
        }
      },
      : 
    });

     ;
  }

  () {
     .;
  }

  
   () {
     operation = .(path, method);
     (!operation) {
        ();
    }

     responseSpec = operation.[status];
     (!responseSpec) {
        ();
    }

     schema = responseSpec.?.[]?.;
     (!schema) {
       { :  };  
    }

    
     .(response, schema);
  }

  () {
     pathItem = ..[path];
     pathItem?.[method.()];
  }

  () {
    
    
      = ();
     ajv =  ();
     valid = ajv.(schema, data);

     {
      valid,
      : ajv.
    };
  }
}


 validator =   ().();
app.(validator.());

Example 3: Custom Business Rule Validation

// validators/business-rules.js
class BusinessRuleValidator {
  constructor() {
    this.rules = new Map();
    this.registerDefaultRules();
  }

  registerDefaultRules() {
    // User-related rules
    this.addRule('user.ageRestriction', (user) => {
      if (user.role === 'admin' && user.age < 21) {
        return 'Admins must be at least 21 years old';
      }
      return null;
    });

    this.addRule('user.emailDomain', (user) => {
      if (user.role === 'employee' && !user.email.endsWith('@company.com')) {
        return 'Employees must use company email';
      }
      return null;
    });

    // Order-related rules
    this.addRule('order.minimumAmount', (order) => {
      const total = order..(
        sum + (item. * item.), 
      );
       (total < ) {
         ;
      }
       ;
    });

    .(,  (order) => {
       ( item  order.) {
         available =  (item.);
         (available < item.) {
           ;
        }
      }
       ;
    });
  }

  () {
    ..(name, validator);
  }

   () {
     errors = [];
     applicableRules = .(..())
      .( name.(context));

     ( [name, validator]  applicableRules) {
       {
         error =  (data);
         (error) {
          errors.({
            : name,
            : error
          });
        }
      }  (e) {
        errors.({
          : name,
          : 
        });
      }
    }

     {
      : errors. === ,
      errors
    };
  }
}


  () {
   originalJson = res.;
   validator =  ();

  res. =  () {
     context = (req.);

     (context) {
       result =  validator.(context, data);

       (!result.) {
        .(, result.);

        
         (process.. === ) {
           originalJson.(, {
            : ,
            : result.
          });
        }
      }
    }

     originalJson.(, data);
  };

  ();
}

Error Handling

Error	Cause	Solution
"Schema not found"	Missing schema file	Ensure schema exists in schemas/ directory
"Invalid schema"	Malformed JSON Schema	Validate schema with JSON Schema validator
"Circular reference"	Schema references itself	Refactor schema to avoid circular dependencies
"Performance degradation"	Large payload validation	Use streaming validation or async processing
"Memory leak"	Schema compilation on every request	Cache compiled validators

Configuration Options

Validation Modes

• strict: Reject invalid responses (production)
• permissive: Log but allow invalid responses (development)
• monitor: Send metrics without blocking (staging)

Performance Tuning

• cacheSize: Number of compiled schemas to cache (default: 100)
• maxDepth: Maximum recursion depth for nested objects (default: 10)
• timeout: Maximum validation time in ms (default: 1000)

Best Practices

DO:

• Version your schemas alongside API versions
• Use shared schema definitions for common types
• Validate at multiple layers (client, server, database)
• Include examples in schema definitions
• Monitor validation failures in production
• Use semantic versioning for schema changes

DON'T:

• Validate responses in production synchronously (use async)
• Include sensitive data in validation error messages
• Use overly strict validation that breaks compatibility
• Ignore validation errors in production
• Mix validation logic with business logic

Performance Considerations

• Compile schemas once at startup, not per request
• Use references for shared schema components
• Consider async validation for large payloads
• Implement sampling for high-traffic endpoints
• Cache validation results for identical responses

Related Commands

• /api-contract-generator - Generate schemas from code
• /api-documentation-generator - Document schemas
• /api-testing-framework - Test against schemas
• /api-versioning-manager - Handle schema evolution

Version History

• v1.0.0 (2024-10): Initial implementation with JSON Schema validation
• Planned v1.1.0: GraphQL schema validation support