Validators

This section describes the available validation rules.

required

Description:
Ensures the field is not empty.

Additional:
Accepts an optional error message. Additionally, accepts a when function that returns a boolean value. If the function returns false, the validation is skipped. Defaults to () => true.

Example:

{
  "validate": "required",
  "when": (row) => row['employee.type'] === 'other'
}

---

unique

Description:
Ensures the value is unique across rows.

Additional:
Accepts an optional error message. Set caseInsensitive to true to compare string values case-insensitively.

---

regex_matches

Description:
Validates a field against a regular expression.

Additional:
Expects a regex and an optional error message.

---

includes

Description:
Checks if a value is within a predefined list.

Additional:
Requires a list of valid values.

---

multi_includes

Description:
Checks if all delimited values are valid.

Additional:
Accepts values, a delimiter, and an optional error message.

---

boolean

Description:
Ensures the value is a real boolean (true / false). Empty values pass; a value that couldn’t be coerced to a boolean (i.e. it matched neither the column’s true nor false tokens) fails.

Additional:
Added automatically to every boolean column, so you normally don’t configure it. You can also add it explicitly to provide a custom error message.

---

date

Description:
Ensures the value is a valid date / datetime / time and, optionally, within a configured range. Empty values pass; a value that couldn’t be parsed against the column’s format (or the ISO fallback) fails.

Additional:
Added automatically to every date, datetime, and time column, using that column’s outputFormat, displayFormat, min, and max, so you normally don’t configure it. Out-of-range values report a distinct error. You can also add it explicitly to provide a custom error message.

---

is_integer

Description:
Validates that the value is an integer.

Additional:
Optional error message.

---

phone_number

Description:
Validates phone number formatting.

Additional:
Optional error message.

---

email

Description:
Validates email format.

Pragmatic email validation based on: https://www.regular-expressions.info/email.html

• Case-insensitive
• Prevents consecutive dots in domain
• Intentionally not RFC 5322 complete

For more restrictive needs please use regex_matches validator.

Additional:
Optional error message.

---

postal_code

Description:
Validates postal code format.

Additional:
Optional error message.

---

custom

Description:
Custom validation function.

Additional:
Requires a key and a validateFn that returns an error message if validation fails. The validateFn may be synchronous or asynchronous — it may return a string | null | undefined or a Promise<string | null | undefined>.

Example (async):

{
  validate: 'custom',
  key: 'email_remote_check',
  validateFn: async (value) => {
    if (value && typeof value === 'string') {
      // simulate async check (e.g. remote service)
      const isEmailValid = await fetch('/api/validate-email', { method: 'POST', body: value });
      if(!isEmailValid) {
        return 'This email is too short';
      }
    }
    return undefined;
  },
}