FormSchema API

Complete reference for FormSchema structure, field definitions, and configuration options.

FormSchema Interface

The main schema object that defines your form structure.

Property	Type	Required	Description
id	string	Yes	Unique identifier for the form
title	string	Yes	Form title displayed to users
description	string	No	Optional form description
fields	FieldDefinition[]	Yes	Array of field definitions
settings	FormSettings	No	Form-level configuration
version	string	No	Schema version for tracking
createdAt	Date	No	Creation timestamp
updatedAt	Date	No	Last update timestamp

FormSettings Interface

Optional settings to customize form behavior and appearance.

Property	Type	Default	Description
submitButtonText	string	"Submit"	Text for submit button
cancelButtonText	string	"Cancel"	Text for cancel button
showLabels	boolean	true	Show field labels
labelPosition	'top' \| 'left' \| 'right'	'top'	Label position relative to field
theme	'light' \| 'dark'	'light'	Form theme
clearOnSubmit	boolean	false	Clear form after submission

FieldValidation Interface

Validation rules applicable to form fields.

Property	Type	Description
required	boolean	Field must have a value
minLength	number	Minimum string length
maxLength	number	Maximum string length
min	number	Minimum numeric value
max	number	Maximum numeric value
pattern	string	Regex pattern for validation
customMessage	string	Custom error message

FieldConditions Interface

Conditional logic for showing/hiding fields dynamically.

tsx

interface FieldConditions {
  show?: ConditionRule[];  // Show field when conditions are met
  hide?: ConditionRule[];  // Hide field when conditions are met
  logic?: 'and' | 'or';    // How to combine multiple conditions (default: 'and')
}

interface ConditionRule {
  fieldId: string;              // The field to check
  operator: ConditionOperator;  // Comparison operator
  value?: any;                  // Value to compare against
}

type ConditionOperator =
  // Boolean operators
  | 'is_checked'
  | 'is_not_checked'
  // Comparison operators
  | 'equals'
  | 'not_equals'
  | 'contains'
  | 'not_contains'
  | 'starts_with'
  | 'ends_with'
  | 'is_empty'
  | 'is_not_empty'
  // Numeric operators
  | 'greater_than'
  | 'less_than'
  | 'greater_than_or_equal'
  | 'less_than_or_equal'
  // Array operators
  | 'includes'
  | 'not_includes';

Example Usage

tsx

const schema: FormSchema = {
  id: 'user-registration',
  title: 'User Registration',
  description: 'Create your account',
  fields: [
    {
      id: '1',
      type: 'text',
      name: 'username',
      label: 'Username',
      required: true,
      validation: {
        minLength: 3,
        maxLength: 20,
        pattern: '^[a-zA-Z0-9_]+$',
        customMessage: 'Username must be 3-20 alphanumeric characters'
      }
    },
    {
      id: '2',
      type: 'email',
      name: 'email',
      label: 'Email',
      required: true
    },
    {
      id: '3',
      type: 'password',
      name: 'password',
      label: 'Password',
      required: true,
      validation: {
        minLength: 8,
        customMessage: 'Password must be at least 8 characters'
      }
    },
    {
      id: '4',
      type: 'checkbox',
      name: 'subscribe',
      label: 'Subscribe to newsletter'
    },
    {
      id: '5',
      type: 'text',
      name: 'referralCode',
      label: 'Referral Code',
      conditions: {
        show: [
          {
            fieldId: '4',
            operator: 'is_checked'
          }
        ]
      }
    }
  ],
  settings: {
    submitButtonText: 'Create Account',
    cancelButtonText: 'Reset',
    theme: 'light',
    clearOnSubmit: false
  },
  version: '1.0.0'
};

💡 Best Practices

• Use unique IDs for all fields to enable proper tracking
• Keep field names consistent with your backend API
• Provide clear validation messages to guide users
• Use conditional logic sparingly to avoid complexity
• Version your schemas for easier tracking and migrations