Schema

The survey schema is the backbone of every survey — a JSON-serializable structure that defines pages, questions, validation, and conditional logic.

SurveySchema

SurveySchematypescript

interface SurveySchema {
  id: string;                    // Unique survey identifier
  title?: string;                // Survey title
  description?: string;          // Survey description
  pages: Page[];                 // Array of pages
  settings?: SurveySettings;     // Global settings
}

Page

Pagetypescript

interface Page {
  id: string;                    // Unique page identifier
  title?: string;                // Page title
  description?: string;          // Page description
  questions: Question[];         // Array of questions
  visibleIf?: string;            // Condition expression
}

Question

Questiontypescript

interface Question {
  id: string;                    // Unique question identifier
  type: QuestionType;            // 'text' | 'textarea' | 'radio' | 'checkbox' | 'select' | 'number' | 'email' | 'date' | 'time' | 'datetime' | 'slider' | 'phone' | 'rating' | 'boolean' | string
  label: string;                 // Question label/title
  description?: string;          // Help text
  placeholder?: string;          // Input placeholder
  required?: boolean;            // Is required?
  defaultValue?: AnswerValue;    // Default answer value
  options?: Option[];            // For radio/checkbox/select
  validation?: ValidationRule[]; // Validation rules
  visibleIf?: string;            // Condition expression: "{role} === 'admin'" or "{consent} === true"
  meta?: Record<string, unknown>; // Custom metadata
}

Question Types

Type	Description	Value Type
`text`	Single-line text input	`string`
`textarea`	Multi-line text input	`string`
`email`	Email input with validation	`string`
`number`	Numeric input	`number`
`phone`	Phone number with country code	`string`
`radio`	Single selection from options	`string`
`checkbox`	Multiple selection from options	`string[]`
`select`	Dropdown selection	`string`
`date`	Date picker	`string`
`time`	Time picker	`string`
`datetime`	Date & time picker	`string`
`slider`	Range slider (min/max/step)	`number`
`rating`	Star rating (1-N)	`number`
`boolean`	Yes/No toggle	`boolean`

SurveySettings

SurveySettingstypescript

interface SurveySettings {
  showProgress?: boolean;          // Show progress bar (default: true)
  allowBack?: boolean;             // Allow navigating to previous pages (default: true)
  validateOnPageChange?: boolean;  // Validate current page before navigating (default: true)
  showQuestionNumbers?: boolean;   // Show question numbers
  submitText?: string;             // Submit button text (default: "Submit")
  nextText?: string;               // Next button text (default: "Next")
  prevText?: string;               // Previous button text (default: "Previous")
}

Full Example

Complete Schema Exampletsx

const schema: SurveySchema = {
  id: 'employee-feedback',
  title: 'Employee Satisfaction Survey',
  description: 'Help us improve your workplace experience.',
  pages: [
    {
      id: 'personal',
      title: 'Personal Information',
      questions: [
        { id: 'name', type: 'text', label: 'Full name', required: true },
        {
          id: 'department',
          type: 'select',
          label: 'Department',
          required: true,
          options: [
            { label: 'Engineering', value: 'eng' },
            { label: 'Design', value: 'design' },
            { label: 'Marketing', value: 'marketing' },
            { label: 'Other', value: 'other' },
          ],
        },
      ],
    },
    {
      id: 'feedback',
      title: 'Your Feedback',
      questions: [
        {
          id: 'rating',
          type: 'rating',
          label: 'Overall satisfaction',
          required: true,
        },
        {
          id: 'improvements',
          type: 'checkbox',
          label: 'What areas need improvement?',
          options: [
            { label: 'Communication', value: 'communication' },
            { label: 'Work-life balance', value: 'balance' },
            { label: 'Career growth', value: 'growth' },
            { label: 'Management', value: 'management' },
          ],
        },
        {
          id: 'details',
          type: 'textarea',
          label: 'Tell us more',
          visibleIf: '{rating} <= 3',
          placeholder: 'What can we do better?',
        },
      ],
    },
  ],
  settings: {
    showProgress: true,
    allowBack: true,
    submitText: 'Submit Feedback',
  },
};