Field Types

Fields define the columns your users will import data into. Each field has atype that controls validation and UI behavior.

Field Interface

interface Field {
  name: string;        // Field identifier (used as key in output)
  label: string;       // Display label shown to the user
  required?: boolean;  // Is this field required? (default: false)
  type?: 'text' | 'email' | 'number' | 'date' | 'enum';
  enum?: EnumDefinition;
  validate?: ValidationRule[];
}

Type Behavior

text

The default field type. Accepts any string value. Use this for names, addresses, notes, or any free-form text.

{
  name: 'company',
  label: 'Company Name',
  type: 'text',        // optional — text is the default
  required: true,
}

email

Automatically validates that values are in a valid email format. You do not need to add a separate email validation rule — the type handles it.

{
  name: 'email',
  label: 'Email Address',
  type: 'email',
  required: true,
}

number

Validates that the input is numeric. Combine with min andmax validation rules to enforce ranges.

{
  name: 'age',
  label: 'Age',
  type: 'number',
  validate: [
    { type: 'min', value: 0 },
    { type: 'max', value: 150 },
  ],
}

date

Accepts date strings. There is no built-in format enforcement yet — values are passed through as-is. Use a regex validation rule if you need a specific format.

{
  name: 'startDate',
  label: 'Start Date',
  type: 'date',
  validate: [
    { type: 'regex', value: '^\\d{4}-\\d{2}-\\d{2}$', message: 'Use YYYY-MM-DD format' },
  ],
}

enum

Enum fields render a dropdown and use a 6-step AI matching cascade to map CSV values to your allowed values. This is the most powerful field type for data normalization.

EnumDefinition Interface

interface EnumDefinition {
  values: string[];      // Allowed values
  hints?: string[];      // AI synonym hints
  allowEmpty?: boolean;  // Allow empty/null values (default: false)
  defaultValue?: string; // Fallback when no match found
}

Example with Hints

{
  name: 'status',
  label: 'Status',
  type: 'enum',
  enum: {
    values: ['active', 'inactive', 'pending'],
    hints: [
      'active: enabled, on, yes, true, 1',
      'inactive: disabled, off, no, false, 0',
      'pending: waiting, hold, review',
    ],
    allowEmpty: false,
    defaultValue: 'pending',
  },
}

6-Step Matching Cascade

When a CSV value needs to be matched to an enum value, ImportKit runs through the following steps in order, stopping at the first match:

1. Exact match — value matches an enum value exactly
2. Case-insensitive match — value matches ignoring case (e.g. "Active" → "active")
3. Customer learned mappings — mappings your users have confirmed in previous imports
4. Global learned mappings — mappings learned across all ImportKit customers
5. Hint-based matching — value matches a synonym from the hints array
6. AI semantic matching — AI determines the closest enum value by meaning

Each match includes a confidence score that is displayed in the value mapping review UI, so your users can verify and correct matches before importing.

Combining Types with Validation Rules

Field types provide baseline validation. You can add extra rules via thevalidate array for more specific constraints:

{
  name: 'sku',
  label: 'Product SKU',
  type: 'text',
  required: true,
  validate: [
    { type: 'regex', value: '^[A-Z]{2}\\d{4}$', message: 'SKU must be 2 letters + 4 digits' },
    { type: 'minLength', value: 6 },
    { type: 'maxLength', value: 6 },
  ],
}

See the API Reference for the full list of validation rule types.