ValidationSchema

A declarative, JSON-based validation system powered by Joi. Define comprehensive validation rules using exact JSON schema syntax with case-sensitive field names and precise validation structure. This documentation reflects the production validation schema exactly as implemented.

Introduction

ValidationSchema is a powerful, declarative validation system that uses exact JSON syntax to define validation rules. The system is built on Joi and provides type-safe, reusable validation schemas that work across client and server environments.

⚠️ Important: JSON Schema Syntax is Case-Sensitive

Field names and validation keys must match exactly as specified. The validation system is highly sensitive to key names and structure. Always use the exact syntax shown in the examples below.

Core Structure

Every validation schema follows this exact structure:

{
  "fieldName": {
    "type": "dataType",
    "required": true,
    "dataType": {
      // Type-specific validation rules
    }
  }
}

Key Benefits

  • Declarative: Define rules using precise JSON objects
  • Type-safe: Built-in TypeScript support with exact typing
  • Reusable: Share schemas across multiple forms
  • Composable: Combine and extend schemas
  • Case-sensitive: Exact key matching ensures consistency

Validator Types Overview

Complete list of supported validator types and their key properties:

Validator Type Key Properties Description
String pattern, creditCard, hostname, alphanum, length, insensitive, ip, domain, email, base64, case, token, uri, dataUri, min, max Text validation with regex, format, and length constraints
Number port, positive, multiple, negative, precision, less, greater, min, max Numeric validation with range, precision, and mathematical constraints
Integer port, positive, multiple, negative, precision, less, greater, min, max Whole number validation (same as number but ensures integer values)
Date less, greater, min, max, iso, timestamp Date validation with range and format constraints
Boolean falsy, truthy, sensitive Boolean validation with custom truthy/falsy values
Object schema Object validation with nested schema definition
Array items, minItems, maxItems, uniqueItems Array validation with item constraints and uniqueness

Production Schema Structure

The validation system follows this exact TypeScript interface structure:

export interface ValidatorBodyModel {
    type: 'string' | 'number' | 'integer' | 'date' | 'boolean' | 'array' | 'object';
    required?: boolean;    
    string?: StringValidatorModel;
    number?: NumberValidatorModel;
    date?: DateValidatorModel;
    boolean?: BooleanValidatorModel;
    object?: ObjectValidatorModel;
    array?: ArrayValidatorModel;    
}

Each validator type has its dedicated interface with specific validation parameters. The system automatically maps JSON validation rules to the appropriate TypeScript interfaces for type safety and validation.

String Validation

String validation uses the exact "string" key with nested validation rules:

Basic String Validation

{
  "username": {
    "type": "string",
    "required": true,
    "string": {
      "min": 3,
      "max": 20,
      "pattern": "^[a-zA-Z0-9_]+$"
    }
  }
}

Email Validation

{
  "email": {
    "type": "string",
    "required": true,
    "string": {
      "email": {
        "allowFullyQualified": false,
        "allowUnicode": false
      }
    }
  }
}

String Validation Properties

Property Type Required Description
"pattern" string Optional Regular expression pattern for validation
"creditCard" boolean Optional Validate as credit card number
"hostname" boolean Optional Validate as valid hostname
"alphanum" boolean Optional Must contain only alphanumeric characters
"length" number Optional Exact string length required
"insensitive" string[] Optional Case-insensitive match against array of values
"ip" object Optional IP address validation rules
"domain" object Optional Domain validation rules
"email" object Optional Email-specific validation rules
"base64" object Optional Base64 validation rules
"case" 'lower' | 'upper' Optional Case requirement (lowercase or uppercase)
"token" boolean Optional Must be a valid token format
"uri" object Optional URI validation rules
"dataUri" boolean Optional Validate as data URI format
"min" number Optional Minimum string length allowed
"max" number Optional Maximum string length allowed

IP Address Validation

{
  "ipAddress": {
    "type": "string",
    "string": {
      "ip": {
        "version": ["ipv4", "ipv6"],
        "cidr": "optional"
      }
    }
  }
}

Domain Validation

{
  "domain": {
    "type": "string",
    "string": {
      "domain": {
        "allowFullyQualified": true,
        "allowUnicode": false,
        "minDomainSegments": 2,
        "maxDomainSegments": 5
      }
    }
  }
}

Email Validation

{
  "email": {
    "type": "string",
    "string": {
      "email": {
        "allowFullyQualified": false,
        "allowUnicode": false,
        "minDomainSegments": 2,
        "maxDomainSegments": 4,
        "ignoreLength": false,
        "multiple": false,
        "separator": ","
      }
    }
  }
}

Base64 Validation

{
  "encodedData": {
    "type": "string",
    "string": {
      "base64": {
        "paddingRequired": true
      }
    }
  }
}

URI Validation

{
  "website": {
    "type": "string",
    "string": {
      "uri": {
        "scheme": ["http", "https"]
      }
    }
  }
}

Number Validation

Number validation uses the exact "number" key with numeric validation rules:

Basic Number Validation

{
  "age": {
    "type": "number",
    "required": true,
    "number": {
      "min": 18,
      "max": 120,
      "precision": 0
    }
  }
}

Number Validation Properties

Property Type Required Description
"port" boolean Optional Validate as valid port number (1-65535)
"positive" boolean Optional Must be a positive number
"multiple" number Optional Must be a multiple of this value
"negative" boolean Optional Must be a negative number
"precision" number Optional Number of decimal places allowed
"less" number Optional Must be less than this value
"greater" number Optional Must be greater than this value
"min" number Optional Minimum allowed numeric value
"max" number Optional Maximum allowed numeric value

Boolean Validation

Boolean validation uses the exact "boolean" key:

Basic Boolean Validation

{
  "isActive": {
    "type": "boolean",
    "required": true,
    "boolean": {
      "default": false
    }
  }
}

Boolean Validation Properties

Property Type Required Description
"falsy" string Optional String values considered as false
"truthy" string Optional String values considered as true
"sensitive" boolean Optional Treat as sensitive data (for logging/security)

Date Validation

Date validation uses the exact "date" key with date-specific validation rules:

Basic Date Validation

{
  "birthDate": {
    "type": "date",
    "required": true,
    "date": {
      "min": "1900-01-01",
      "max": "now",
      "iso": true
    }
  }
}

Date Validation Properties

Property Type Required Description
"less" 'now' | string | Date Optional Date must be less than this value
"greater" 'now' | string | Date Optional Date must be greater than this value
"min" 'now' | string | Date Optional Minimum allowed date value
"max" 'now' | string | Date Optional Maximum allowed date value
"iso" boolean Optional Must be valid ISO 8601 date format
"timestamp" 'javascript' | 'unix' Optional Validate as specific timestamp format

Integer Validation

Integer validation uses the exact "integer" key for whole numbers:

Basic Integer Validation

{
  "quantity": {
    "type": "integer",
    "required": true,
    "integer": {
      "min": 1,
      "max": 100,
      "positive": true
    }
  }
}

Integer Validation Properties

Integer validation uses the same properties as number validation, but ensures whole number values.

Property Type Required Description
"port" boolean Optional Validate as valid port number (1-65535)
"positive" boolean Optional Must be a positive integer
"multiple" number Optional Must be a multiple of this value
"negative" boolean Optional Must be a negative integer
"precision" number Optional Number of decimal places allowed (typically 0 for integers)
"less" number Optional Must be less than this value
"greater" number Optional Must be greater than this value
"min" number Optional Minimum allowed integer value
"max" number Optional Maximum allowed integer value

Object Validation

Object validation uses the exact "object" key with nested schema definition:

Basic Object Validation

{
  "address": {
    "type": "object",
    "required": true,
    "object": {
      "schema": {
        "street": {
          "type": "string",
          "required": true,
          "string": {
            "min": 5,
            "max": 100
          }
        },
        "city": {
          "type": "string",
          "required": true,
          "string": {
            "min": 2,
            "max": 50
          }
        }
      }
    }
  }
}

Object Validation Properties

Property Type Required Description
"schema" object Required Nested validation schema for object properties

Array Validation

Array validation uses the exact "array" key with item validation rules:

Basic Array Validation

{
  "tags": {
    "type": "array",
    "required": false,
    "array": {
      "minItems": 1,
      "maxItems": 10,
      "items": {
        "type": "string",
        "string": {
          "min": 2,
          "max": 20
        }
      }
    }
  }
}

Array Validation Properties

Property Type Required Description
"items" object Optional Validation schema for individual array items
"minItems" number Optional Minimum number of array items required
"maxItems" number Optional Maximum number of array items allowed
"uniqueItems" boolean Optional All array items must be unique

Comprehensive Validation Examples

Complete examples showing all validator types with their production parameters:

String Validation Examples

{
  "username": {
    "type": "string",
    "required": true,
    "string": {
      "alphanum": true,
      "min": 3,
      "max": 20,
      "case": "lower"
    }
  },
  "email": {
    "type": "string",
    "required": true,
    "string": {
      "email": {
        "allowFullyQualified": false,
        "allowUnicode": false,
        "minDomainSegments": 2,
        "maxDomainSegments": 4
      }
    }
  },
  "ipAddress": {
    "type": "string",
    "string": {
      "ip": {
        "version": ["ipv4"],
        "cidr": "forbidden"
      }
    }
  },
  "website": {
    "type": "string",
    "string": {
      "uri": {
        "scheme": ["http", "https"]
      }
    }
  }
}

Number and Integer Validation Examples

{
  "age": {
    "type": "integer",
    "required": true,
    "integer": {
      "min": 18,
      "max": 120,
      "positive": true
    }
  },
  "port": {
    "type": "number",
    "number": {
      "port": true
    }
  },
  "percentage": {
    "type": "number",
    "number": {
      "min": 0,
      "max": 100,
      "precision": 2
    }
  },
  "multiple": {
    "type": "integer",
    "integer": {
      "multiple": 5,
      "positive": true
    }
  }
}

Date Validation Examples

{
  "birthDate": {
    "type": "date",
    "date": {
      "max": "now",
      "iso": true
    }
  },
  "expiryDate": {
    "type": "date",
    "date": {
      "greater": "now",
      "iso": true
    }
  },
  "eventDate": {
    "type": "date",
    "date": {
      "min": "2024-01-01",
      "max": "2025-12-31"
    }
  }
}

Boolean Validation Examples

{
  "isActive": {
    "type": "boolean",
    "boolean": {
      "truthy": "yes",
      "falsy": "no",
      "sensitive": false
    }
  },
  "termsAccepted": {
    "type": "boolean",
    "required": true,
    "boolean": {
      "truthy": "accepted",
      "sensitive": true
    }
  }
}

Array and Object Validation Examples

{
  "tags": {
    "type": "array",
    "array": {
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "string": {
          "min": 2,
          "max": 20
        }
      }
    }
  },
  "address": {
    "type": "object",
    "object": {
      "schema": {
        "street": {
          "type": "string",
          "string": {
            "min": 5,
            "max": 100
          }
        },
        "city": {
          "type": "string",
          "string": {
            "min": 2,
            "max": 50
          }
        }
      }
    }
  }
}

Integration

Complete integration example showing:

  • API payload structure design
  • Validation schema creation
  • Form component configuration
  • Data binding and validation flow

Sample API Payload

Here's a sample API payload structure for a simple form:


  {
    "name": "John Doe",
    "age": 25,
    "email": "john@example.com"
  }

Validation Schema

Create a validation schema to validate the API payload:

{
  "name": {
    "type": "string",
    "required": true,
    "string": {
      "min": 2,
      "max": 50
    }
  },
  "age": {
    "type": "number",
    "required": true,
    "number": {
      "min": 18,
      "max": 120,
      "positive": true
    }
  },
  "email": {
    "type": "string",
    "required": true,
    "string": {
      "email": {
        "allowFullyQualified": false,
        "allowUnicode": false
      }
    }
  }
}

Form Component Schema

Create a form schema using only text and number components:

{
  "type": "form",
  "validatorSchema": {
    "name": {
      "type": "string",
      "required": true,
      "string": {
        "min": 2,
        "max": 50
      }
    },
    "age": {
      "type": "number",
      "required": true,
      "number": {
        "min": 18,
        "max": 120,
        "positive": true
      }
    },
    "email": {
      "type": "string",
      "required": true,
      "string": {
        "email": {
          "allowFullyQualified": false,
          "allowUnicode": false
        }
      }
    }
  },
  "components": [
    {
      "type": "text",
      "name": "name",
      "label": "Full Name",
      "placeholder": "Enter your full name"
    },
    {
      "type": "number",
      "name": "age",
      "label": "Age",
      "placeholder": "Enter your age"
    },
    {
      "type": "text",
      "name": "email",
      "label": "Email Address",
      "placeholder": "Enter your email"
    },
    {
      "type": "button",
      "btnType": "submit",
      "text": "Save"
    }
  ]
}

Note: You can use {"type":"text","name":""} for binding form fields to validation rules. The name property should match the field names in your validation schema.

Integration Flow

Follow these steps to integrate your form with validation:

  • API Payload Design: Define the expected data structure for your API
  • Validation Schema Creation: Create validation rules that match your API payload structure
  • Form Component Mapping: Map form components to validation schema fields using the name property
  • Data Binding: Use {"type":"text","name":"fieldName"} for binding form inputs to validation rules
  • Form Rendering: The form engine renders components based on your form schema
  • Real-time Validation: Client-side validation occurs as users type
  • Data Submission: Validated data is sent to your API endpoint

Key Integration Points

  • Component Binding: Use the name property to link form fields to validation rules
  • Schema Consistency: Ensure your form component names match exactly with validation schema field names
  • Type Matching: Component types should align with validation types (text → string, number → number)
  • Required Fields: Set "required": true for mandatory form fields
  • Validation Rules: Apply appropriate validation constraints based on your business requirements

Schema Generator

Generate a basic validation schema from your API payload. This tool creates a starting point that you can further enhance based on your specific requirements.

Input API Payload

Paste your JSON API payload below:

Generated Validation Schema

Your generated schema will appear here:

// Generated schema will appear here...

How to Use

  • Step 1: Paste your JSON API payload in the input field above
  • Step 2: Click "Generate Validation Schema" to convert your payload
  • Step 3: Review the generated schema and copy it for use
  • Step 4: Enhance the generated schema with specific validation rules as needed

Generator Features

  • Automatic Type Detection: Analyzes your payload and determines appropriate validation types
  • Nested Object Support: Handles complex nested structures and arrays
  • Standard Compliance: Generates schemas that follow our established validation standards
  • Starting Point: Provides a basic foundation that you can customize and enhance