String

String fields use x.string() for text values. Supports format validators like .email(), .url(), and length constraints.

x.string().label("Company Name").min(2).max(100)

columnNameAliases

Adds alternate CSV header names for this field.

.columnNameAliases(aliases: string[])

aliases lists header names that should map to this schema key, e.g., ["Email", "Email Address"].
Aliases are used during column matching alongside the field key and label. They do not change the output object key.

label

Sets the user-facing label shown in the importer.

.label(text: string)

text sets the label text.

description

Sets help text shown below the field.

.description(text: string)

text sets the description text.

optional

Allows the field to be empty.

.optional()

Empty optional values are delivered as null.
The row object still includes the field key, e.g., { middleName: null }.

default

Available after .optional().

.default(defaultValue: unknown | (() => unknown | Promise<unknown>))

defaultValue can be a static value or a function used when the field is empty, e.g., "Unknown" or () => new Date().toISOString().
Defaults apply to missing values, null, empty strings, and whitespace-only strings.
When a default is used, it is returned directly instead of validating or refining the empty value.

email

Validates email format.

.email(options?: { message?: string })

message overrides the validation error text, e.g., "Enter a valid email address".

.url(options?: { allowedProtocols?: ("http" | "https" | "ftp" | "sftp" | "file" | "mailto" | "tel")[]; allowedDomains?: string[]; allowSubdomains?: boolean; allowPaths?: boolean; allowQueryParams?: boolean; message?: string })

allowedProtocols restricts accepted protocols, e.g., ["https"] or ["https", "mailto"].
allowedDomains restricts accepted domains, e.g., ["example.com"].
allowSubdomains controls whether subdomains are accepted.
allowPaths controls whether paths are accepted.
allowQueryParams controls whether query strings are accepted.
message overrides the validation error text, e.g., "Only company URLs are allowed".

uuid

Validates UUIDs.

.uuid(options?: { version?: "v1" | "v4" | "v5" | "all"; message?: string })

version restricts the accepted UUID version, e.g., "v4" or "all".
message overrides the validation error text, e.g., "Use a valid UUID".

ip

Validates IP addresses.

.ip(options?: { version?: "v4" | "v6" | "all"; message?: string })

version restricts the accepted IP version, e.g., "v4", "v6", or "all".
message overrides the validation error text, e.g., "Enter a valid IP address".

phone

Validates phone numbers.

.phone(options?: { allowedCountries?: string[]; format?: "international" | "national" | "both"; output?: "e164" | "formatted" | "digits"; message?: string })

allowedCountries restricts input to ISO 3166-1 alpha-2 country codes, e.g., ["US"] or ["US", "CA"].
format controls the expected input format, e.g., "international", "national", or "both".
output controls the normalized output format, e.g., "e164", "formatted", or "digits".
message overrides the validation error text, e.g., "Enter a valid US phone number".

country

Validates country names or codes.

.country(options?: { output?: "name" | "2-letter" | "3-letter"; message?: string })

output controls the parsed country format, e.g., "name", "2-letter", or "3-letter".
message overrides the validation error text, e.g., "Enter a valid country".

alphabetical

Restricts values to letters only.

.alphabetical(options?: { message?: string })

message overrides the validation error text, e.g., "Use letters only".

alphanumerical

Restricts values to letters and numbers only.

.alphanumerical(options?: { message?: string })

message overrides the validation error text, e.g., "Use letters and numbers only".

numerical

Restricts values to numeric characters only.

.numerical(options?: { message?: string })

message overrides the validation error text, e.g., "Use numeric characters only".

regex

Matches a regular expression.

.regex(pattern: RegExp, options?: { message?: string })

pattern is the regular expression to match, e.g., /^[A-Z]{3}-\d{4}$/.
message overrides the validation error text, e.g., "Use format ABC-1234".

iban

Validates IBAN values.

.iban(options?: { allowedCountries?: string[]; message?: string })

allowedCountries restricts input to ISO 3166-1 alpha-2 country codes, e.g., ["DE"] or ["DE", "FR"].
message overrides the validation error text, e.g., "Enter a valid EU IBAN".

bic

Validates BIC/SWIFT codes.

.bic(options?: { message?: string })

message overrides the validation error text, e.g., "Enter a valid BIC/SWIFT code".

gtin

Validates GTIN values.

.gtin(options?: { message?: string })

message overrides the validation error text, e.g., "Enter a valid GTIN".

currencyCode

Validates ISO 4217 currency codes.

.currencyCode(options?: { allowedCurrencies?: string[]; message?: string })

allowedCurrencies restricts input to specific currency codes, e.g., ["USD"] or ["USD", "EUR"].
message overrides the validation error text, e.g., "Use a supported currency code".