Request Validation

Validate incoming HTTP requests against JSON schemas and custom rules. Define body, query parameter, header, and path parameter validation with configurable modes to enforce, warn, log, or disable validation.

Prerequisites

• An existing mock simulation with routes
• Understanding of JSON Schema syntax (optional but helpful)
• Basic knowledge of HTTP request components

Understanding Request Validation

Request validation allows you to:

• Define expected request structure using JSON Schema
• Validate request bodies, query parameters, headers, and path parameters
• Choose how to handle validation failures (strict, warn, log only, or disabled)
• Customize error response templates
• Track validation failures for debugging
• Ensure consumers send properly formatted requests

Setting Up Validation Schemas

Access Route Validation

1. Navigate to a route in your simulation
2. Click Edit Route or the gear icon
3. Select the Validation or Schema tab
4. Click Add Schema or Configure Validation

Define Body Schema

Create a JSON Schema for request body validation:

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

Define Query Parameter Schema

Validate query parameters:

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": 1
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "filter": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9]+$"
    }
  },
  "required": ["page"]
}

Define Header Rules

Configure header-level validation with custom rules:

[
  {
    "name": "X-Api-Key",
    "required": true,
    "pattern": "^[a-zA-Z0-9]+$"
  },
  {
    "name": "Authorization",
    "required": true,
    "pattern": "^Bearer .+$"
  },
  {
    "name": "X-Request-Id",
    "required": false,
    "pattern": "^[0-9a-f-]{36}$"
  }
]

Header Rule Fields:

• name - Header name (case-insensitive matching)
• required - Whether the header must be present
• pattern - Regular expression the value must match

Define Path Parameter Rules

Validate dynamic path parameters:

[
  {
    "name": "userId",
    "required": true,
    "pattern": "^[0-9a-f-]{36}$"
  },
  {
    "name": "version",
    "required": true,
    "pattern": "^v[0-9]+$"
  }
]

Choosing Validation Modes

Validation modes control how the mock handles validation failures:

Mode	Behavior	Use Case
strict	Reject invalid requests with error response	Production-ready validation
warn	Accept request but include warning headers	Development/testing with feedback
log_only	Accept request and log failure silently	Audit/monitoring without blocking
disabled	Skip validation entirely	Debugging or feature flags

Set Validation Mode for a Route

1. Open route validation settings
2. Select validation mode:
   • Strict - Return error response
   • Warn - Include X-Validation-Warning header
   • Log Only - Accept but record failure
   • Disabled - No validation

Set Simulation-Wide Validation Mode

Apply validation mode to all routes in a simulation:

1. Open simulation settings
2. Navigate to Validation Settings
3. Click Set Simulation Validation Mode
4. Select the mode (strict, warn, log_only, disabled)
5. Confirm - applies to all routes without explicit overrides

Routes with explicit mode settings keep those settings. Only routes using the default inherit the simulation-wide setting.

Customizing Error Format

Define how validation errors are returned in error responses.

Access Error Format Settings

1. Navigate to simulation settings
2. Click Error Format or Validation Error Template

Create Error Format Template

{
  "errorCode": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": {
    "errors": [
      {
        "field": "name",
        "message": "must be a string",
        "type": "type"
      },
      {
        "field": "email",
        "message": "must be a valid email",
        "type": "format"
      }
    ]
  },
  "timestamp": "2026-01-15T10:30:00Z"
}

Template Variables

Use these placeholders in your error template:

• {errorCode} - The validation error code
• {message} - Summary message
• {details} - Array of validation errors
• {timestamp} - ISO 8601 timestamp
• {field} - Failed field name
• {value} - Actual value sent
• {expected} - Expected constraint description

Example Custom Template

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "{message}",
    "validationErrors": "{details}",
    "requestId": "{requestId}",
    "timestamp": "{timestamp}"
  }
}

Validation Failure Logging

View Validation Failures

1. Open simulation dashboard
2. Navigate to Validation section
3. Click Failures or Validation Log

View recent validation failures with:

• Request timestamp
• Route that failed validation
• Failure reason (which field/rule failed)
• Request data (body, query, headers)
• Consumer information (IP, User-Agent)

Failure Summary

Click Failure Summary to see aggregate statistics:

• Total failures in time period
• Top failing routes (by count)
• Top failing fields (by count)
• Most common failure types
• Error breakdown by validation rule

Export Failures

Export validation failure logs for analysis:

1. Click Export
2. Select time range
3. Choose format (CSV, JSON)
4. Download the file

Common Validation Scenarios

Require Specific Headers

Ensure consumers send required authentication headers:

{
  "name": "Authorization",
  "required": true,
  "pattern": "^Bearer [a-zA-Z0-9\\-._~+/]+=*$"
}

Enforce Email Format

Validate email addresses in request body:

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["email"]
}

Validate UUID Parameters

Ensure path parameters are valid UUIDs:

[
  {
    "name": "id",
    "required": true,
    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
  }
]

Paginated Query Parameters

Enforce pagination constraints:

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "minimum": 1,
      "default": 1
    },
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    }
  },
  "required": ["page", "pageSize"]
}

Nested Object Validation

Validate complex request structures:

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" },
        "profile": {
          "type": "object",
          "properties": {
            "bio": { "type": "string" },
            "avatar_url": { "type": "string", "format": "uri" }
          }
        }
      },
      "required": ["name", "email"]
    }
  },
  "required": ["user"]
}

Array Validation

Validate arrays with item constraints:

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1 }
        },
        "required": ["id", "quantity"]
      },
      "minItems": 1,
      "maxItems": 50
    }
  }
}

Validation Workflow

Typical Development Workflow

1. Development - Use log_only mode to track what would fail
2. Testing - Use warn mode to get feedback in response headers
3. Staging - Use strict mode to test error handling
4. Production - Use strict mode for enforcement

Switching Modes for Debugging

1. If tests fail validation in strict mode:
   • Switch to warn mode temporarily
   • Check response headers for validation warnings
   • See exact failure details
   • Fix the request format
   • Switch back to strict

Troubleshooting

Validation Not Triggering

• Verify validation mode is not disabled
• Check schema is correctly formatted JSON
• Ensure route-level schema takes precedence over simulation setting
• Review validation logs to see if rule is matching

Schema Syntax Errors

• Use a JSON Schema validator tool to check schema
• Common mistakes: missing required array, malformed regex patterns
• Verify property types match actual request data

Header Validation Not Working

• Header names are case-insensitive but patterns are case-sensitive
• Use regex patterns for flexible matching
• Remember to escape special characters in regex patterns

False Positives in Validation

• Review pattern regex for overly strict rules
• Check JSON Schema constraints (minLength, maxLength, etc.)
• Test schema separately with various inputs
• Consider using warn mode if strict enforcement is too aggressive

API Reference

Validation Endpoints

Method	Path	Description
GET	/routes/:id/schema	Get request schema
PUT	/routes/:id/schema	Create/update schema
DELETE	/routes/:id/schema	Delete schema
GET	/instances/:id/validation-mode	Get simulation validation mode
PATCH	/instances/:id/validation-mode	Set simulation validation mode

Failure Tracking Endpoints

Method	Path	Description
GET	/instances/:id/validation-failures	List failures
GET	/instances/:id/validation-failures/summary	Get summary stats

Next Steps

• Routes and Responses - Learn about route configuration
• Response Versioning - Track response changes
• Analytics - Monitor validation metrics in traffic analysis