Skip to main content

Survey Question Types Reference

This comprehensive reference covers all supported question types in the Cimigo Collect Platform. Each question type is designed for specific data collection needs and includes schema definitions, examples, and implementation guidance.

📋 Table of Contents​

  1. Survey Definition Structure
  2. Schema Versioning
  3. Question Types Overview
  4. Base Question Structure
  5. Question Types:
  6. Complete Survey Examples
  7. Survey Definition Management
  8. Response Data Structure
  9. Best Practices
  10. Technical Implementation

🏗️ Survey Definition Structure​

A complete survey definition consists of several key components that work together to create a comprehensive data collection experience.

Root Survey Definition Schema​

interface SurveyDefinition {
  schema_version: string;           // Required: Schema version (e.g., "1.2")
  version: number;                  // Required: Definition version number
  survey: Survey;                   // Required: Main survey object
  theme?: ThemeConfig;              // Optional: Visual customization
  logic?: LogicRule[];              // Optional: Advanced conditional logic
  validation?: ValidationConfig;    // Optional: Custom validation rules
}

Core Survey Object​

interface Survey {
  id?: string;                           // Optional: Auto-generated if not provided
  title: LocalisedText;                  // Required: Survey title
  description?: LocalisedText;           // Optional: Survey description
  pages: Page[];                         // Required: Survey pages (at least 1)
  locale?: string;                       // Optional: Default locale
  metadata?: Record<string, any>;        // Optional: Custom metadata
  supported_languages?: string[];        // Required for schema >= 1.2
  welcome_message?: LocalisedText;       // Optional: Welcome screen message
  thank_you_message?: LocalisedText;     // Optional: Thank you screen message
  settings?: SurveySettings;             // Optional: Survey behavior settings
}

Survey Settings​

interface SurveySettings {
  // Navigation and UI Settings
  allow_back_navigation?: boolean;       // Allow previous page navigation (default: true)
  progress_bar?: boolean;               // Display completion progress (default: true)
  show_title?: boolean;                 // Show survey title to respondents (default: false)
  show_description?: boolean;           // Show survey description to respondents (default: false)
  
  // Completion Settings
  completion_redirect_url?: string;     // URL to redirect after completion (must be HTTP/HTTPS)
  
  // Advanced Settings
  allow_multiple_responses?: boolean;   // Allow multiple responses from same user
  randomize_questions?: boolean;        // Randomize question order within pages
  
  // Custom properties
  [key: string]: any;                   // Additional custom settings
}

Page Structure​

interface Page {
  id?: string;                          // Optional: Auto-generated if not provided
  title?: LocalisedText;                // Optional: Page title
  description?: LocalisedText;          // Optional: Page description
  questions: Question[];                // Required: Questions on this page
}

Localized Text Format​

// Single language (string)
type LocalisedText = string | Record<string, string>;

// Examples:
const singleLanguage: LocalisedText = "Welcome to our survey";

const multiLanguage: LocalisedText = {
  "en": "Welcome to our survey",
  "fr": "Bienvenue à notre enquête",
  "es": "Bienvenido a nuestra encuesta"
};

📋 Schema Versioning​

The platform uses semantic versioning to manage survey schema evolution and ensure backward compatibility.

Supported Schema Versions​

VersionRelease DateKey FeaturesStatus
1.0InitialBasic question types (single, multiple, text, textarea, likert, rating, nps, matrix)✅ Stable
1.1Q2 2024Date question type, improved validation✅ Stable
1.2Q3 2024Required supported_languages, performance improvements✅ Current
1.3Q4 2024File upload, advanced logic (planned)🚧 Planned

Schema Version Requirements​

Schema 1.0 (Legacy)​

  • Question Types: single, multiple, text, textarea, likert, rating, nps, matrix
  • Languages: Auto-detected from content (performance impact)
  • Validation: Basic client-side validation

Schema 1.1 (Enhanced)​

  • New Features: Date question type
  • Improvements: Enhanced validation, better error messages
  • Backward Compatible: All 1.0 features supported

Schema 1.2 (Current)​

  • Required Field: supported_languages array
  • Performance: Optimized language handling
  • Features: All previous question types plus enhanced localization

Schema 1.3 (Upcoming)​

  • Planned Features: File upload questions, advanced conditional logic
  • Breaking Changes: None (backward compatible)

Version Migration Guide​

// Migrating from 1.1 to 1.2
const survey_v11 = {
  schema_version: "1.1",
  survey: {
    title: "Customer Feedback",
    // supported_languages missing (auto-detected)
  }
};

const survey_v12 = {
  schema_version: "1.2", 
  survey: {
    title: "Customer Feedback",
    supported_languages: ["en", "fr"], // Now required
  }
};

📋 Question Types Overview​

Question TypePurposeResponse FormatSchema Version
Single ChoiceSelect one option from a listString (option ID)1.0+
Multiple ChoiceSelect multiple options from a listArray of strings1.0+
Text InputShort text responsesString1.0+
TextareaLong text responsesString1.0+
Likert ScaleAgreement/disagreement scaleNumber or "NA"1.0+
RatingStar or numeric ratingNumber1.0+
NPSNet Promoter Score (0-10)Number or "NA"1.0+
MatrixMultiple attributes on same scaleObject with attribute keys1.0+
DateDate selection with constraintsISO date string (YYYY-MM-DD)1.1+

🔧 Base Question Structure​

All questions inherit from a base structure:

interface QuestionBase {
  id: string;                    // Unique identifier
  type: string;                  // Question type
  title: LocalisedText;          // Question title
  description?: LocalisedText;   // Optional description
  required?: boolean;            // Required field (default: false)
  visibleIf?: {                  // Conditional visibility
    dependsOn: string;           // ID of question to depend on
    equalsAnyOf: Array<string | number | boolean>;
  };
}

// LocalisedText can be a string or object with language codes
type LocalisedText = string | Record<string, string>;

Conditional Logic Example​

{
  "id": "follow_up_question",
  "type": "text", 
  "title": "What specific improvements would you like to see?",
  "visibleIf": {
    "dependsOn": "satisfaction_rating",
    "equalsAnyOf": [1, 2, 3]
  }
}

Single Choice Question​

Purpose: Allows respondents to select exactly one option from a predefined list. Perfect for categorical data, preferences, and mutually exclusive choices.

Schema Definition​

interface SingleQuestion extends QuestionBase {
  type: "single";
  options: Option[];
}

interface Option {
  id: string;
  label: LocalisedText;
  value?: string | number;  // Optional custom value
}

Basic Example​

{
  "id": "preferred_contact",
  "type": "single",
  "title": "How would you prefer to be contacted?",
  "required": true,
  "options": [
    {
      "id": "email",
      "label": "Email"
    },
    {
      "id": "phone", 
      "label": "Phone call"
    },
    {
      "id": "text",
      "label": "Text message"
    },
    {
      "id": "mail",
      "label": "Postal mail"
    }
  ]
}

Localized Example​

{
  "id": "satisfaction_level",
  "type": "single",
  "title": {
    "en": "How satisfied are you with our service?",
    "es": "¿Qué tan satisfecho está con nuestro servicio?",
    "fr": "À quel point êtes-vous satisfait de notre service?"
  },
  "options": [
    {
      "id": "very_satisfied",
      "label": {
        "en": "Very satisfied",
        "es": "Muy satisfecho", 
        "fr": "Très satisfait"
      }
    },
    {
      "id": "satisfied",
      "label": {
        "en": "Satisfied",
        "es": "Satisfecho",
        "fr": "Satisfait"
      }
    }
  ]
}

Response Format​

{
  "preferred_contact": "email"
}

Multiple Choice Question​

Purpose: Allows respondents to select multiple options from a predefined list. Ideal for collecting multiple preferences, features, or interests.

Schema Definition​

interface MultipleQuestion extends QuestionBase {
  type: "multiple";
  options: Option[];
  maxSelect?: number;  // Maximum selections allowed
  minSelect?: number;  // Minimum selections required
}

Basic Example​

{
  "id": "interests",
  "type": "multiple",
  "title": "Which topics are you interested in?",
  "description": "Select all that apply (max 3)",
  "maxSelect": 3,
  "minSelect": 1,
  "options": [
    {"id": "technology", "label": "Technology"},
    {"id": "sports", "label": "Sports"},
    {"id": "music", "label": "Music"},
    {"id": "travel", "label": "Travel"},
    {"id": "cooking", "label": "Cooking"},
    {"id": "reading", "label": "Reading"}
  ]
}

Professional Skills Example​

{
  "id": "programming_languages",
  "type": "multiple", 
  "title": "Which programming languages do you use professionally?",
  "maxSelect": 5,
  "visibleIf": {
    "dependsOn": "job_role",
    "equalsAnyOf": ["developer", "engineer", "data_scientist"]
  },
  "options": [
    {"id": "javascript", "label": "JavaScript"},
    {"id": "python", "label": "Python"},
    {"id": "java", "label": "Java"},
    {"id": "csharp", "label": "C#"},
    {"id": "go", "label": "Go"},
    {"id": "rust", "label": "Rust"}
  ]
}

Response Format​

{
  "interests": ["technology", "music", "travel"]
}

Text Question​

Purpose: Collects short text input from respondents. Perfect for names, emails, job titles, or brief answers.

Schema Definition​

interface TextQuestion extends QuestionBase {
  type: "text";
  placeholder?: LocalisedText;  // Input placeholder text
  maxLength?: number;           // Maximum character limit
}

Basic Examples​

[
  {
    "id": "full_name",
    "type": "text", 
    "title": "What is your full name?",
    "placeholder": "Enter your full name",
    "required": true,
    "maxLength": 100
  },
  {
    "id": "email_address",
    "type": "text",
    "title": "What is your email address?", 
    "placeholder": "example@company.com",
    "required": true,
    "maxLength": 255
  },
  {
    "id": "job_title",
    "type": "text",
    "title": "What is your current job title?",
    "placeholder": "e.g., Software Engineer, Marketing Manager",
    "maxLength": 150
  }
]

Localized Example​

{
  "id": "company_name",
  "type": "text",
  "title": {
    "en": "What is your company name?",
    "es": "¿Cuál es el nombre de su empresa?",
    "fr": "Quel est le nom de votre entreprise?"
  },
  "placeholder": {
    "en": "Enter company name",
    "es": "Ingrese el nombre de la empresa", 
    "fr": "Entrez le nom de l'entreprise"
  },
  "maxLength": 200
}

Response Format​

{
  "full_name": "John Smith",
  "email_address": "john.smith@example.com"
}

Textarea Question​

Purpose: Collects longer text input from respondents. Ideal for detailed feedback, comments, suggestions, or explanations.

Schema Definition​

interface TextAreaQuestion extends QuestionBase {
  type: "textarea";
  placeholder?: LocalisedText;  // Input placeholder text
  maxLength?: number;           // Maximum character limit
}

Feedback Examples​

[
  {
    "id": "detailed_feedback",
    "type": "textarea",
    "title": "Please provide detailed feedback about your experience",
    "placeholder": "Share your thoughts, suggestions, or concerns...",
    "maxLength": 1000
  },
  {
    "id": "product_review",
    "type": "textarea",
    "title": "Write a detailed review of the product",
    "description": "Include what you liked, what could be improved, and any other relevant details",
    "placeholder": "I found this product to be...",
    "required": true,
    "maxLength": 2000
  },
  {
    "id": "improvement_suggestions",
    "type": "textarea",
    "title": "What improvements would you like to see?",
    "placeholder": "Please be specific about features or areas for improvement",
    "maxLength": 500
  }
]

Response Format​

{
  "detailed_feedback": "The service was excellent and exceeded my expectations. The staff was very helpful and responsive to all my questions. I would definitely recommend this to others."
}

Likert Scale Question​

Purpose: Measures attitudes or opinions using a symmetric agree-disagree scale. Standard for measuring agreement, satisfaction, or likelihood across multiple statements.

Schema Definition​

interface LikertQuestion extends QuestionBase {
  type: "likert";
  scale: {
    from: number;                    // Starting number (e.g., 1)
    to: number;                      // Ending number (e.g., 5)
    leftLabel?: LocalisedText;       // Label for lowest value
    rightLabel?: LocalisedText;      // Label for highest value
    includeNA?: boolean;             // Include "Not Applicable" option
    naLabel?: LocalisedText;         // Label for N/A option
  };
}

5-Point Agreement Scale​

{
  "id": "product_ease_of_use",
  "type": "likert",
  "title": "This product is easy to use",
  "required": true,
  "scale": {
    "from": 1,
    "to": 5,
    "leftLabel": "Strongly disagree",
    "rightLabel": "Strongly agree",
    "includeNA": true,
    "naLabel": "Not applicable"
  }
}

7-Point Scale Example​

{
  "id": "recommendation_likelihood",
  "type": "likert", 
  "title": "I would recommend this service to others",
  "scale": {
    "from": 1,
    "to": 7,
    "leftLabel": "Strongly disagree",
    "rightLabel": "Strongly agree"
  }
}

Localized Example​

{
  "id": "value_for_money",
  "type": "likert",
  "title": {
    "en": "This product offers good value for money",
    "es": "Este producto ofrece una buena relación calidad-precio",
    "fr": "Ce produit offre un bon rapport qualité-prix"
  },
  "scale": {
    "from": 1,
    "to": 5,
    "leftLabel": {
      "en": "Strongly disagree",
      "es": "Totalmente en desacuerdo",
      "fr": "Totalement en désaccord"
    },
    "rightLabel": {
      "en": "Strongly agree", 
      "es": "Totalmente de acuerdo",
      "fr": "Totalement d'accord"
    },
    "includeNA": true,
    "naLabel": {
      "en": "Not applicable",
      "es": "No aplica",
      "fr": "Non applicable"
    }
  }
}

Response Format​

{
  "product_ease_of_use": 4,
  "value_for_money": "NA"
}

Rating Question​

Purpose: Collects ratings using a star-based or numeric rating system. Perfect for satisfaction ratings, quality assessments, or experience evaluations.

Schema Definition​

interface RatingQuestion extends QuestionBase {
  type: "rating";
  max: number;                     // Maximum rating value
  leftLabel?: LocalisedText;       // Label for low rating
  rightLabel?: LocalisedText;      // Label for high rating
}

5-Star Rating Examples​

[
  {
    "id": "overall_experience",
    "type": "rating",
    "title": "How would you rate your overall experience?",
    "required": true,
    "max": 5,
    "leftLabel": "Very poor",
    "rightLabel": "Excellent"
  },
  {
    "id": "product_quality",
    "type": "rating", 
    "title": "Rate the quality of our product",
    "max": 5,
    "leftLabel": "Poor quality",
    "rightLabel": "Outstanding quality"
  },
  {
    "id": "ease_of_use",
    "type": "rating",
    "title": "How easy was our product to use?",
    "max": 5,
    "leftLabel": "Very difficult",
    "rightLabel": "Very easy"
  }
]

10-Point Rating Example​

{
  "id": "feature_satisfaction",
  "type": "rating",
  "title": "Rate your satisfaction with our new features",
  "max": 10,
  "leftLabel": "Completely dissatisfied",
  "rightLabel": "Completely satisfied"
}

Localized Example​

{
  "id": "service_rating",
  "type": "rating",
  "title": {
    "en": "Rate our customer service",
    "es": "Califique nuestro servicio al cliente", 
    "fr": "Évaluez notre service client"
  },
  "max": 5,
  "leftLabel": {
    "en": "Very poor",
    "es": "Muy malo",
    "fr": "Très mauvais"
  },
  "rightLabel": {
    "en": "Excellent",
    "es": "Excelente",
    "fr": "Excellent"
  }
}

Response Format​

{
  "overall_experience": 4,
  "product_quality": 5
}

NPS Question​

Purpose: Net Promoter Score question using the standard 0-10 scale to measure customer loyalty and likelihood to recommend. Industry-standard metric for customer satisfaction.

Schema Definition​

interface NpsQuestion extends QuestionBase {
  type: "nps";
  leftLabel?: LocalisedText;       // Label for 0 (low)
  rightLabel?: LocalisedText;      // Label for 10 (high)
  includeNA?: boolean;             // Include "Not Applicable" option
  naLabel?: LocalisedText;         // Label for N/A option
}

Standard NPS Examples​

[
  {
    "id": "nps_score",
    "type": "nps",
    "title": "How likely are you to recommend our company to a friend or colleague?",
    "required": true,
    "leftLabel": "Not at all likely",
    "rightLabel": "Extremely likely"
  },
  {
    "id": "product_nps",
    "type": "nps",
    "title": "How likely are you to recommend this specific product?",
    "leftLabel": "Not at all likely", 
    "rightLabel": "Extremely likely",
    "includeNA": true,
    "naLabel": "Haven't used this product"
  }
]

Service-Specific NPS​

{
  "id": "support_nps",
  "type": "nps",
  "title": "Based on your recent support experience, how likely are you to recommend our support team?",
  "leftLabel": "Not at all likely",
  "rightLabel": "Extremely likely",
  "visibleIf": {
    "dependsOn": "contacted_support",
    "equalsAnyOf": [true, "yes"]
  }
}

Localized NPS Example​

{
  "id": "brand_nps",
  "type": "nps",
  "title": {
    "en": "How likely are you to recommend our brand to others?",
    "es": "¿Qué tan probable es que recomiende nuestra marca a otros?",
    "fr": "Quelle est la probabilité que vous recommandiez notre marque à d'autres?"
  },
  "leftLabel": {
    "en": "Not at all likely",
    "es": "Para nada probable",
    "fr": "Pas du tout probable"
  },
  "rightLabel": {
    "en": "Extremely likely",
    "es": "Extremadamente probable", 
    "fr": "Extrêmement probable"
  }
}

Response Format​

{
  "nps_score": 8,
  "product_nps": "NA"
}

NPS Scoring Categories​

  • 0-6: Detractors (unhappy customers)
  • 7-8: Passives (neutral customers)
  • 9-10: Promoters (loyal advocates)

NPS Score Calculation: % Promoters - % Detractors

Matrix Likert Question​

Purpose: Allows multiple related statements to be rated using the same Likert scale. Efficiently collects data on multiple attributes while maintaining consistency in measurement.

Schema Definition​

interface MatrixLikertQuestion extends QuestionBase {
  type: "matrix";
  scale: {
    from: number;
    to: number;
    leftLabel?: LocalisedText;
    rightLabel?: LocalisedText;
    includeNA?: boolean;
    naLabel?: LocalisedText;
  };
  attributes: Array<{
    id: string;
    label: LocalisedText;
  }>;
  rotate?: boolean;  // Future: rotate matrix display
}

Service Evaluation Matrix​

{
  "id": "service_aspects",
  "type": "matrix",
  "title": "Please rate the following aspects of our service",
  "required": true,
  "scale": {
    "from": 1,
    "to": 5,
    "leftLabel": "Very poor",
    "rightLabel": "Excellent",
    "includeNA": true,
    "naLabel": "Not applicable"
  },
  "attributes": [
    {
      "id": "responsiveness", 
      "label": "Response time"
    },
    {
      "id": "friendliness",
      "label": "Staff friendliness"
    },
    {
      "id": "knowledge",
      "label": "Staff knowledge" 
    },
    {
      "id": "resolution",
      "label": "Problem resolution"
    }
  ]
}

Product Features Matrix​

{
  "id": "product_features",
  "type": "matrix",
  "title": "Rate your satisfaction with these product features",
  "scale": {
    "from": 1,
    "to": 7,
    "leftLabel": "Very dissatisfied",
    "rightLabel": "Very satisfied",
    "includeNA": true,
    "naLabel": "Don't use this feature"
  },
  "attributes": [
    {
      "id": "user_interface",
      "label": "User interface design"
    },
    {
      "id": "performance", 
      "label": "Speed and performance"
    },
    {
      "id": "reliability",
      "label": "Reliability and stability"
    },
    {
      "id": "features",
      "label": "Available features"
    },
    {
      "id": "documentation",
      "label": "Documentation quality"
    }
  ]
}

Localized Matrix Example​

{
  "id": "website_evaluation",
  "type": "matrix",
  "title": {
    "en": "Evaluate our website on the following criteria",
    "es": "Evalúe nuestro sitio web según los siguientes criterios",
    "fr": "Évaluez notre site web selon les critères suivants"
  },
  "scale": {
    "from": 1,
    "to": 5,
    "leftLabel": {
      "en": "Poor",
      "es": "Malo",
      "fr": "Mauvais"
    },
    "rightLabel": {
      "en": "Excellent",
      "es": "Excelente",
      "fr": "Excellent"
    }
  },
  "attributes": [
    {
      "id": "ease_of_navigation",
      "label": {
        "en": "Ease of navigation",
        "es": "Facilidad de navegación",
        "fr": "Facilité de navigation"
      }
    },
    {
      "id": "visual_design",
      "label": {
        "en": "Visual design",
        "es": "Diseño visual",
        "fr": "Design visuel"
      }
    },
    {
      "id": "loading_speed",
      "label": {
        "en": "Loading speed",
        "es": "Velocidad de carga",
        "fr": "Vitesse de chargement"
      }
    }
  ]
}

Response Format​

Matrix questions generate multiple response keys using the pattern questionId__attributeId:

{
  "service_aspects__responsiveness": 4,
  "service_aspects__friendliness": 5,
  "service_aspects__knowledge": 3,
  "service_aspects__resolution": "NA"
}

Date Question​

Purpose: Collects date information from respondents with optional constraints. Perfect for appointments, deadlines, birth dates, or event dates.

Schema Definition​

interface DateQuestion extends QuestionBase {
  type: "date";
  min_date?: string;  // Minimum allowed date (YYYY-MM-DD)
  max_date?: string;  // Maximum allowed date (YYYY-MM-DD)
}

Note: Date questions require schema_version >= 1.1

Basic Date Examples​

[
  {
    "id": "birth_date",
    "type": "date",
    "title": "What is your date of birth?",
    "required": true
  },
  {
    "id": "preferred_start_date",
    "type": "date", 
    "title": "When would you prefer to start?",
    "description": "Please select your preferred start date",
    "min_date": "2025-09-10"
  }
]

Date with Constraints​

{
  "id": "appointment_date",
  "type": "date",
  "title": "Select your preferred appointment date",
  "description": "Please choose a date within the next 30 days",
  "required": true,
  "min_date": "2025-09-10",
  "max_date": "2025-10-10"
}

Past Date Example​

{
  "id": "last_purchase_date",
  "type": "date",
  "title": "When did you last make a purchase with us?",
  "max_date": "2025-09-09"
}

Localized Date Example​

{
  "id": "event_date",
  "type": "date", 
  "title": {
    "en": "When would you like to schedule the event?",
    "es": "¿Cuándo le gustaría programar el evento?",
    "fr": "Quand aimeriez-vous programmer l'événement?"
  },
  "min_date": "2025-09-15",
  "max_date": "2025-12-31"
}

Response Format​

{
  "birth_date": "1990-05-15",
  "appointment_date": "2025-09-25"
}

🏗️ Complete Survey Examples​

1. Customer Satisfaction Survey (Simple)​

{
  "schema_version": "1.2",
  "version": 1,
  "survey": {
    "id": "customer_satisfaction_2024",
    "title": {
      "en": "Customer Satisfaction Survey",
      "fr": "Enquête de satisfaction client"
    },
    "description": {
      "en": "Help us improve our service by sharing your experience",
      "fr": "Aidez-nous à améliorer notre service en partageant votre expérience"
    },
    "supported_languages": ["en", "fr"],
    "locale": "en",
    "welcome_message": {
      "en": "Thank you for taking the time to provide feedback. Your responses will help us serve you better.",
      "fr": "Merci de prendre le temps de nous faire part de vos commentaires. Vos réponses nous aideront à mieux vous servir."
    },
    "thank_you_message": {
      "en": "Thank you for your valuable feedback! We appreciate your time and input.",
      "fr": "Merci pour vos précieux commentaires ! Nous apprécions votre temps et votre contribution."
    },
    "settings": {
      "progress_bar": true,
      "allow_back_navigation": true,
      "show_title": false,
      "show_description": false
    },
    "pages": [
      {
        "id": "demographics",
        "title": {
          "en": "About You",
          "fr": "À propos de vous"
        },
        "questions": [
          {
            "id": "age_group",
            "type": "single",
            "title": {
              "en": "What is your age group?",
              "fr": "Quel est votre groupe d'âge ?"
            },
            "required": true,
            "options": [
              {
                "id": "18-24",
                "label": "18-24"
              },
              {
                "id": "25-34", 
                "label": "25-34"
              },
              {
                "id": "35-44",
                "label": "35-44"
              },
              {
                "id": "45-54",
                "label": "45-54"
              },
              {
                "id": "55+",
                "label": {
                  "en": "55 or older",
                  "fr": "55 ans ou plus"
                }
              }
            ]
          },
          {
            "id": "customer_type",
            "type": "single",
            "title": {
              "en": "How long have you been our customer?",
              "fr": "Depuis combien de temps êtes-vous notre client ?"
            },
            "required": true,
            "options": [
              {
                "id": "new",
                "label": {
                  "en": "Less than 6 months",
                  "fr": "Moins de 6 mois"
                }
              },
              {
                "id": "regular",
                "label": {
                  "en": "6 months to 2 years",
                  "fr": "6 mois à 2 ans"
                }
              },
              {
                "id": "loyal",
                "label": {
                  "en": "More than 2 years",
                  "fr": "Plus de 2 ans"
                }
              }
            ]
          }
        ]
      },
      {
        "id": "satisfaction",
        "title": {
          "en": "Your Experience",
          "fr": "Votre expérience"
        },
        "questions": [
          {
            "id": "overall_satisfaction",
            "type": "rating",
            "title": {
              "en": "How would you rate your overall satisfaction?",
              "fr": "Comment évalueriez-vous votre satisfaction globale ?"
            },
            "required": true,
            "max": 5,
            "leftLabel": {
              "en": "Very dissatisfied",
              "fr": "Très insatisfait"
            },
            "rightLabel": {
              "en": "Very satisfied",
              "fr": "Très satisfait"
            }
          },
          {
            "id": "service_aspects",
            "type": "matrix",
            "title": {
              "en": "Please rate the following aspects of our service",
              "fr": "Veuillez évaluer les aspects suivants de notre service"
            },
            "required": true,
            "scale": {
              "from": 1,
              "to": 5,
              "leftLabel": {
                "en": "Poor",
                "fr": "Médiocre"
              },
              "rightLabel": {
                "en": "Excellent",
                "fr": "Excellent"
              },
              "includeNA": true,
              "naLabel": {
                "en": "Not applicable",
                "fr": "Non applicable"
              }
            },
            "attributes": [
              {
                "id": "speed",
                "label": {
                  "en": "Speed of service",
                  "fr": "Rapidité du service"
                }
              },
              {
                "id": "quality",
                "label": {
                  "en": "Quality of service",
                  "fr": "Qualité du service"
                }
              },
              {
                "id": "staff_friendliness",
                "label": {
                  "en": "Staff friendliness",
                  "fr": "Amabilité du personnel"
                }
              },
              {
                "id": "value_for_money",
                "label": {
                  "en": "Value for money",
                  "fr": "Rapport qualité-prix"
                }
              }
            ]
          },
          {
            "id": "nps_score",
            "type": "nps",
            "title": {
              "en": "How likely are you to recommend us to friends or colleagues?",
              "fr": "Quelle est la probabilité que vous nous recommandiez à des amis ou collègues ?"
            },
            "required": true,
            "leftLabel": {
              "en": "Not at all likely",
              "fr": "Pas du tout probable"
            },
            "rightLabel": {
              "en": "Extremely likely",
              "fr": "Extrêmement probable"
            }
          }
        ]
      },
      {
        "id": "feedback",
        "title": {
          "en": "Additional Feedback",
          "fr": "Commentaires supplémentaires"
        },
        "questions": [
          {
            "id": "improvements",
            "type": "textarea",
            "title": {
              "en": "What improvements would you like to see?",
              "fr": "Quelles améliorations aimeriez-vous voir ?"
            },
            "description": {
              "en": "Please share any suggestions for how we can serve you better",
              "fr": "Veuillez partager toute suggestion sur la façon dont nous pouvons mieux vous servir"
            },
            "placeholder": {
              "en": "Your suggestions here...",
              "fr": "Vos suggestions ici..."
            },
            "maxLength": 1000,
            "visibleIf": {
              "dependsOn": "overall_satisfaction",
              "equalsAnyOf": [1, 2, 3]
            }
          },
          {
            "id": "contact_permission",
            "type": "single",
            "title": {
              "en": "May we contact you for follow-up questions?",
              "fr": "Pouvons-nous vous contacter pour des questions de suivi ?"
            },
            "options": [
              {
                "id": "yes",
                "label": {
                  "en": "Yes, you may contact me",
                  "fr": "Oui, vous pouvez me contacter"
                }
              },
              {
                "id": "no",
                "label": {
                  "en": "No, please do not contact me",
                  "fr": "Non, veuillez ne pas me contacter"
                }
              }
            ]
          },
          {
            "id": "contact_email",
            "type": "text",
            "title": {
              "en": "What is the best email to reach you?",
              "fr": "Quel est le meilleur email pour vous joindre ?"
            },
            "placeholder": {
              "en": "your.email@example.com",
              "fr": "votre.email@exemple.com"
            },
            "maxLength": 255,
            "visibleIf": {
              "dependsOn": "contact_permission",
              "equalsAnyOf": ["yes"]
            }
          }
        ]
      }
    ],
    "metadata": {
      "created_by": "survey_admin",
      "department": "customer_success",
      "campaign": "q3_2024_satisfaction"
    }
  },
  "theme": {
    "primaryColor": "#007bff",
    "backgroundColor": "#f8f9fa",
    "textColor": "#333333",
    "fontFamily": "Arial, sans-serif"
  }
}

2. Product Feedback Survey (With Date Questions - Schema 1.2)​

{
  "schema_version": "1.2",
  "version": 1,
  "survey": {
    "id": "product_feedback_beta_test",
    "title": "Beta Product Feedback Survey",
    "description": "Help us improve our new product before launch",
    "supported_languages": ["en"],
    "locale": "en",
    "welcome_message": "Thank you for participating in our beta test! Your feedback is crucial for making our product the best it can be.",
    "thank_you_message": "Thank you for your detailed feedback! We'll use your insights to make improvements before our official launch.",
    "settings": {
      "progress_bar": true,
      "allow_back_navigation": true,
      "completion_redirect_url": "https://company.com/beta-feedback-thanks"
    },
    "pages": [
      {
        "id": "usage_info",
        "title": "Product Usage",
        "questions": [
          {
            "id": "first_use_date",
            "type": "date",
            "title": "When did you first start using the beta product?",
            "required": true,
            "min_date": "2024-08-01",
            "max_date": "2024-09-09"
          },
          {
            "id": "usage_frequency",
            "type": "single",
            "title": "How often do you use the product?",
            "required": true,
            "options": [
              {"id": "daily", "label": "Daily"},
              {"id": "weekly", "label": "Several times a week"},
              {"id": "monthly", "label": "Several times a month"},
              {"id": "rarely", "label": "Rarely"}
            ]
          }
        ]
      },
      {
        "id": "feature_evaluation",
        "title": "Feature Evaluation",
        "questions": [
          {
            "id": "feature_ratings",
            "type": "matrix",
            "title": "Please rate the following features",
            "required": true,
            "scale": {
              "from": 1,
              "to": 5,
              "leftLabel": "Needs significant improvement",
              "rightLabel": "Excellent",
              "includeNA": true,
              "naLabel": "Haven't used this feature"
            },
            "attributes": [
              {"id": "user_interface", "label": "User interface design"},
              {"id": "performance", "label": "Performance and speed"},
              {"id": "reliability", "label": "Reliability and stability"},
              {"id": "ease_of_use", "label": "Ease of use"}
            ]
          },
          {
            "id": "overall_satisfaction",
            "type": "rating",
            "title": "How satisfied are you with the product overall?",
            "required": true,
            "max": 10,
            "leftLabel": "Completely dissatisfied",
            "rightLabel": "Completely satisfied"
          }
        ]
      }
    ],
    "metadata": {
      "product_version": "0.9.0-beta",
      "test_group": "beta_testers",
      "feedback_type": "product_evaluation"
    }
  }
}

📝 Survey Definition Management​

Creating a Survey Definition​

Survey definitions are created through the platform's API and undergo validation to ensure schema compliance and data integrity.

API Endpoint​

POST /v1/projects/{project_id}/survey-definitions

Request Structure​

{
  "schema_version": "1.2",
  "version": 1,
  "survey": { /* Survey object */ },
  "theme": { /* Optional theme configuration */ },
  "logic": [ /* Optional advanced logic rules */ ],
  "validation": { /* Optional custom validation */ }
}

Validation Process​

The platform performs comprehensive validation on survey definitions:

  1. Schema Version Compliance: Ensures question types are supported in the specified schema version
  2. Language Requirements: Validates supported_languages for schema >= 1.2
  3. Question Structure: Verifies all required fields and data types
  4. Logic Validation: Checks conditional logic dependencies and circular references
  5. Content Analysis: Analyzes localized content for completeness

Survey Definition Lifecycle​

interface SurveyDefinition {
  id: number;                    // Auto-generated unique ID
  project_id: string;            // Parent project identifier
  status: 'draft' | 'active' | 'paused' | 'completed' | 'archived';
  created_at: string;            // ISO 8601 timestamp
  published_at?: string;         // When made active
  schema_version: string;        // Schema version used
  version: number;               // Definition version
  survey: Survey;                // Survey configuration
  theme?: ThemeConfig;           // Visual customization
  logic?: LogicRule[];           // Advanced conditional logic
  validation?: ValidationConfig; // Custom validation rules
}

Status Transitions​

Advanced Features​

Custom Themes​

interface ThemeConfig {
  primaryColor?: string;         // Primary brand color
  backgroundColor?: string;      // Background color
  textColor?: string;           // Text color
  fontFamily?: string;          // Font family
  borderRadius?: string;        // Border radius for elements
  customCSS?: string;           // Custom CSS overrides
  logo?: {
    url: string;                // Logo image URL
    height?: number;            // Logo height in pixels
    position?: 'left' | 'center' | 'right';
  };
}

Logic Rules (Advanced)​

interface LogicRule {
  id: string;                   // Unique rule identifier
  type: 'skip' | 'show' | 'hide' | 'require' | 'calculate';
  condition: LogicCondition;    // When to apply the rule
  action: LogicAction;          // What action to take
  priority?: number;            // Rule execution priority
}

interface LogicCondition {
  operator: 'and' | 'or' | 'not';
  conditions: Array<{
    questionId: string;
    operator: 'equals' | 'not_equals' | 'contains' | 'greater_than' | 'less_than';
    value: any;
  }>;
}

Custom Validation​

interface ValidationConfig {
  email_validation?: boolean;           // Enable email format validation
  phone_validation?: boolean;          // Enable phone number validation
  duplicate_prevention?: boolean;      // Prevent duplicate responses
  required_completion_rate?: number;   // Minimum completion rate (0-1)
  custom_validators?: Array<{
    questionId: string;
    pattern?: string;                  // RegEx pattern
    message: LocalisedText;           // Error message
  }>;
}

Response Collection​

Response Data Structure​

Responses are collected and structured based on question types:

interface SurveyResponse {
  id: string;                          // Unique response ID
  survey_definition_id: number;        // Source survey definition
  respondent_id?: string;              // Optional respondent identifier
  status: 'in_progress' | 'completed' | 'abandoned';
  started_at: string;                  // ISO 8601 timestamp
  completed_at?: string;               // Completion timestamp
  locale: string;                      // Response language
  answers: Record<string, any>;        // Question answers
  metadata: {
    user_agent?: string;               // Browser information
    ip_address?: string;               // IP address (if collected)
    session_id?: string;               // Session identifier
    referrer?: string;                 // Referral source
    completion_time?: number;          // Time to complete (seconds)
  };
}

Response Processing​

The platform automatically processes responses to handle different question types:

{
  "age_group": "25-34",                           // Single choice
  "interests": ["technology", "music"],           // Multiple choice
  "feedback": "Great service overall!",           // Text/Textarea
  "satisfaction_rating": 4,                       // Rating/Likert
  "nps_score": 8,                                // NPS
  "service_aspects__quality": 5,                  // Matrix (expanded)
  "service_aspects__speed": 4,
  "service_aspects__support": "NA",
  "appointment_date": "2024-10-15"               // Date
}

Performance Considerations​

Language Handling​

For optimal performance, always specify supported_languages:

{
  "schema_version": "1.2",
  "survey": {
    "supported_languages": ["en", "fr", "es"],
    // ... rest of survey
  }
}

Benefits:

  • Faster language detection and processing
  • Reduced memory usage during rendering
  • Better caching and optimization
  • Eliminates language inference overhead

Supported Settings​

Only include settings that are actually implemented:

{
  "settings": {
    "progress_bar": true,                    // ✅ Supported - Shows completion progress
    "allow_back_navigation": true,           // ✅ Supported - Previous page navigation  
    "show_title": false,                     // ✅ Supported - Hide/show survey title
    "show_description": false,               // ✅ Supported - Hide/show survey description
    "completion_redirect_url": "https://...", // ✅ Supported - Redirect after completion
    "allow_multiple_responses": true,        // ✅ Supported - Multiple responses per user
    "randomize_questions": false             // ✅ Supported - Question randomization
  }
}

Note: Settings like auto_save_drafts, response_limit, close_date, and collect_metadata are not currently implemented and will be ignored.

Question Limits​

Recommended limits for optimal user experience:

AspectRecommended LimitReason
Total Questions20-30 per surveyPrevents survey fatigue
Questions per Page3-7 questionsMaintains focus and progress
Matrix Attributes5-7 per matrixAvoids overwhelming users
Multiple Choice Options8-12 optionsPrevents choice overload
Text Length500-1000 charsBalances detail with usability

📊 Response Data Structure​

Survey responses are collected as key-value pairs:

{
  "age_group": "25-34",
  "customer_since": "2023-05-15",
  "overall_rating": 4,
  "service_aspects__quality": 5,
  "service_aspects__support": 4,
  "service_aspects__value": 3,
  "service_aspects__delivery": 4,
  "nps": 8,
  "improvements": ["features", "pricing"],
  "additional_comments": "Overall very satisfied with the service quality."
}

🎯 Best Practices​

Question Design​

  1. Keep titles concise - Clear, actionable questions
  2. Use appropriate scales - 5-point for satisfaction, 7-point for agreement
  3. Provide context - Use descriptions for complex questions
  4. Logical flow - Order questions from general to specific

Response Validation​

  1. Set appropriate limits - maxSelect, maxLength, date ranges
  2. Mark essentials as required - But don't overuse required fields
  3. Use conditional logic - visibleIf for relevant follow-ups
  4. Test thoroughly - Validate all question combinations

Localization​

  1. Consistent translations - Maintain meaning across languages
  2. Cultural adaptation - Consider cultural differences in responses
  3. Test with native speakers - Validate translations with real users
  4. Fallback strategy - Handle missing translations gracefully

Performance​

  1. Limit matrix size - Maximum 5-7 attributes per matrix
  2. Reasonable text limits - Balance usability with data quality
  3. Optimize conditional logic - Avoid complex dependency chains
  4. Progressive disclosure - Use pages to break up long surveys

🔧 Technical Implementation​

Frontend Components​

Each question type has a corresponding React component:

// Question type mapping
const QuestionComponents = {
  single: SingleChoiceQuestion,
  multiple: MultipleChoiceQuestion,
  text: TextQuestion,
  textarea: TextQuestion, // Shares implementation
  likert: LikertQuestion,
  rating: RatingQuestion,
  nps: NpsQuestion,
  matrix: MatrixQuestion,
  date: DateQuestion
};

Backend Validation​

Questions are validated using Pydantic schemas:

# Schema version validation
def validate_question_type(schema_version: str, question_type: str):
    allowed_types = get_allowed_types(schema_version)
    if question_type not in allowed_types:
        raise ValueError(f"Question type '{question_type}' not allowed in schema {schema_version}")

Response Processing​

# Response data processing
def process_response_data(survey_definition: dict, response_data: dict):
    processed = {}
    for question in survey_definition['questions']:
        if question['type'] == 'matrix':
            # Handle matrix responses
            for attr in question['attributes']:
                key = f"{question['id']}__{attr['id']}"
                if key in response_data:
                    processed[key] = response_data[key]
        else:
            # Handle regular responses
            if question['id'] in response_data:
                processed[question['id']] = response_data[question['id']]
    return processed

This comprehensive reference covers all question types supported by the Cimigo Collect Platform. Each type is designed for specific use cases and provides flexibility for various data collection needs while maintaining consistency and usability across the platform.