Field types

CloudTable columns are fields, and each field has a type that determines what it stores, how it is edited, and how its values are validated. This page documents every standard field type.

Values are validated and coerced identically on the client and on the server (the same isomorphic validateCell routine runs in both places), so an invalid write is rejected wherever it originates.

Common options

Every field, regardless of type, supports a few shared options:

Option	Applies to	Behavior
description	All types	Optional free-text describing the field.
required	Most types	When set, an empty value is rejected with “This field is required”.
defaultValue	Most types	Pre-filled into new rows.

An empty value (null, undefined, "", or an empty array) is always allowed unless the field is required. Empty required values fail validation; empty non-required values are stored as null.

Text

Type	Label
text	Single line text
long_text	Long text

Stores: a string. long_text is the multi-line variant; both validate identically.

Options:

• maxLength — maximum number of characters. Longer values fail with “Max N characters”.
• regex — a regular-expression pattern the value must match. A non-matching value fails with “Does not match the required format”. An invalid regex in the config is ignored rather than blocking the write.
• required

Validation: the value is coerced with String(value), then checked against maxLength and regex when configured.

Numbers

Type	Label
number	Number
currency	Currency
percent	Percent

Stores: a number. Currency and percent share the same numeric validation as number; they differ only in display.

Options:

• min — lower bound. Values below it fail with “Must be ≥ min”.
• max — upper bound. Values above it fail with “Must be ≤ max”.
• precision — number of decimal places. When set (and >= 0), the value is rounded with toFixed(precision).
• currencySymbol — the symbol shown for currency fields (display only).
• required

Validation: the input is parsed to a number (Number(...)). A non-finite result fails with “Enter a number”. Bounds and precision are then applied.

Rating and checkbox

Type	Label	Stores
rating	Rating	a number
checkbox	Checkbox	a boolean

Rating options:

• ratingMax — the maximum rating (e.g. 5 stars).
• required

Rating validation: the value is coerced to a number; a non-finite result fails with “Invalid rating”.

Checkbox validation: the value is normalized to a strict boolean — it is stored as true only when the input is exactly true, otherwise false.

Choice

Type	Label	Stores
single_select	Single select	a single option string
multi_select	Multiple select	an array of option strings

Options:

• options — the list of allowed choices.
• optionColors — a map of option name to color key, used to render colored chips.
• defaultValue
• required

Validation: single_select passes its value through unchanged. multi_select normalizes the value to an array — a single value is wrapped as [value].

Date

Type	Label
date	Date

Stores: a canonical YYYY-MM-DD string, or YYYY-MM-DDTHH:mm when time is included.

Options:

• dateIncludeTime — when set, the field stores and shows a time component.
• required

Validation: stored/ISO values are normalized directly; human-typed and pasted forms (M/D/YYYY, M/D/YY, Jul 13 2026, with an optional trailing time such as 14:30 or 2:30 pm) are additionally tolerated. Impossible calendar dates (e.g. 2/30) are rejected. Anything unparseable fails with “Enter a valid date”.

Contact

Type	Label	Stores
email	Email	a string
url	URL	a string
phone	Phone	a string

Email validation: the trimmed value must match ^[^\s@]+@[^\s@]+\.[^\s@]+$. Otherwise it fails with “Enter a valid email address”.

URL validation: if the value has no scheme (no protocol://), https:// is prepended automatically. The result must parse as a valid URL, otherwise it fails with “Enter a valid URL”.

example.com        →  https://example.com
http://example.com →  http://example.com   (scheme kept as-is)

Phone validation: after stripping non-digit characters, at least 7 digits must remain, otherwise it fails with “Enter a valid phone number”. The original formatting is preserved as stored.

These types also support required.

Attachment

Type	Label
attachment	Attachment

Stores: uploaded file references. Values pass through validation unchanged.

Link to another record

Type	Label
link	Link to another record

Stores: references to rows in another table.

Options:

• linkedTableId — the table this field links to.
• relationship — the cardinality: one_to_one, one_to_many, or many_to_many.
• symmetricFieldId — the paired field on the other table.
• single — whether this side holds at most one linked record.

Link is a structural field type: it maintains a two-sided relationship between tables and cannot be converted to or from other field types. Its values pass through validation unchanged.

Button

Type	Label
button	Button

A button is an action, not a stored value — clicking it triggers a webhook rather than editing cell data.

Options:

• buttonLabel — the text shown on the button.
• webhookUrl — the URL invoked on click.
• Secret — an optional signing secret, stored encrypted at rest (as secretCiphertext / secretIv / secretTag), never as plaintext.

JSON

Type	Label
json	JSON

Stores: a parsed JSON value (object, array, or scalar).

Validation: when the input is a string, it is parsed with JSON.parse; invalid JSON fails with “Invalid JSON”. Non-string inputs (already-parsed values) are stored as-is.

Computed fields

Three field types are read-only, computed values — you don’t edit them directly; CloudTable derives each row’s value from other fields. They have their own reference pages:

• Formula — an expression evaluated per row.
• Template — {{Field}} interpolation into a text string.
• Code — sandboxed per-row JavaScript.