Field Validation Rules

Every ObjectStack field type has built-in validation behavior that runs automatically at the schema level. This reference documents the default constraints, required properties, and validation semantics for each field type.

Universal Field Constraints

These properties apply to all field types and are validated by the base FieldSchema:

Text Types

text

Default constraints: None. Unbounded text unless maxLength is set.

textarea

Default constraints: None. Multi-line text with no length limit by default.

email

Default constraints: Must contain an @ and a domain with a dot — a lightweight pattern check, not full RFC 5322 validation.

url

Default constraints: Must be a valid URL with protocol prefix.

phone

Default constraints: Accepts digits, + ( ) - . and spaces (minimum 5 characters) — a lenient character-set check, not strict E.164 structural validation.

password

Default constraints: Validated the same as text (maxLength/minLength only). On a generic (non-better-auth) object a password-typed value is stored plaintext at rest but masked to •••••••• on read through the normal query path (ADR-0100) — the engine does not hash or encrypt it. One-way hashing and verification of real login credentials are owned entirely by the auth subsystem (better-auth); its own credential column (sys_account.password) is a hashed Field.text() column that is exempt from this masking. For a reversible, encrypted-at-rest value on your own objects, use the secret type instead.

secret

Default constraints: Reversible, encrypted-at-rest value (DB password, API key, token) — ADR-0100. Fail-closed: with no ICryptoProvider registered, a write throws rather than persisting cleartext. The value is encrypted on write into a sys_secret row, only an opaque handle is persisted on the record, and reads are masked. Distinct from password, which is plaintext at rest (or one-way hashed inside the auth subsystem).

Rich Content Types

markdown

Default constraints: Accepts valid Markdown syntax. No length limit by default.

html

Default constraints: HTML content is sanitized to prevent XSS. No length limit by default.

richtext

Default constraints: Stored as structured rich text (e.g., ProseMirror/Tiptap JSON). Sanitized on save.

Number Types

number

Default constraints: Any valid number. No range or precision limits by default.

currency

Default constraints: Stored as a bare number (a finite numeric scalar — valueSchemaFor routes currency to z.number().finite()); there is no { value, currency } envelope on the value path. The per-record currency code is a separate concern, carried by currencyConfig above. Precision defaults to 2 decimal places.

percent

Default constraints: Stored as decimal (e.g., 0.85 for 85%). No range limit by default.

Date & Time Types

date

Required props: None.
Default constraints: Validates ISO 8601 date format (YYYY-MM-DD). No range restrictions.

datetime

Required props: None.
Default constraints: Validates ISO 8601 datetime format (YYYY-MM-DDTHH:mm:ssZ). Stored in UTC.

time

Required props: None.
Default constraints: Validates ISO 8601 time format (HH:mm:ss). 24-hour format.

Boolean Types

boolean

Default constraints: Only accepts true or false. Renders as checkbox.

toggle

Default constraints: Identical validation to boolean. Distinct UI — renders as toggle switch.

Selection Types

select

Option validation: Each option value must be a lowercase system identifier — starts with a letter, then letters/digits/underscores/dots (^[a-z][a-z0-9_.]*$), minimum 2 characters.

multiselect

Default constraints: Stores array of selected option values. Each value validated against options.

radio

Default constraints: Single-value selection. Same validation as select with radio button UI.

checkboxes

Default constraints: Multi-value selection. Same validation as multiselect with checkbox group UI.

Relational Types

lookup

Default constraints: Validates that referenced record exists. Foreign key integrity enforced.

Multi-value lookups (multiple: true). The empty set is representable: an emptied multi-value lookup is stored and read back as [], never null — including when deleteBehavior: 'set_null' removes the last remaining member. The declared contract lives in the multiple and required doc blocks of packages/spec/src/data/field.zod.ts (rendered in the Field reference), and it makes required on a multi-value lookup mean non-empty array.

user

Default constraints: Person picker — a lookup specialized to the built-in sys_user object, so reference is implied and must not be authored. Stored as a foreign key to sys_user.id and resolved through the same $expand machinery as lookup; with multiple: true the stored value is a JSON array of ids.

master_detail

Default constraints: Enforces parent-child ownership. Child records cascade-delete with the parent by default.

tree

Default constraints: Self-referencing lookup for hierarchical structures. Stored and expanded like a lookup; the engine does not run a cycle check on write, so a self-reference chain that loops back on itself is not automatically rejected.

Media Types

image

Default constraints: Accepts common image MIME types. The schema has no field-level attachment-config property — fileAttachmentConfig was removed in the 16.x line (#2377).

file

Default constraints: Accepts any file type. The Field schema exposes no field-level upload-validation config — fileAttachmentConfig (and its maxSize / allowedTypes / virus-scan sub-keys) was removed in the 16.x line (#2377). File-storage constraints such as virus scanning are configured on the file-storage integration, not on the field.

// File field
{
  name: 'contract_pdf',
  label: 'Contract',
  type: 'file',
  multiple: false
}

avatar

Default constraints: Single image upload. Typically constrained to square aspect ratio and small file sizes.

video

Default constraints: Accepts common video MIME types. The field type has no per-field size/type config property in the schema.

audio

Default constraints: Accepts common audio MIME types. The field type has no per-field size/type config property in the schema.

Computed & System Types

formula

Default constraints: Read-only. Value computed at runtime from expression. Not directly writable.

{
  name: 'full_name',
  label: 'Full Name',
  type: 'formula',
  expression: 'record.first_name + " " + record.last_name'
}

summary

Default constraints: Read-only. Value computed from child records. Only valid on master objects.

autonumber

Default constraints: Read-only. Auto-incremented. Cannot be manually set after creation.

Embedded Structured Types

These types store structured values as JSON on the parent row — no separate table and no foreign key. Sub-field shapes are declared on the field, and the stored value is validated as an open object map (valueSchemaFor), so sub-keys are not constrained by the field type itself.

composite

Default constraints: Single embedded sub-object. Stored as a JSON object map (Record<string, unknown>). No per-type config properties.

repeater

Default constraints: Repeating embedded sub-object array. Stored as a JSON array of object maps (Array<Record<string, unknown>>); a non-array value is rejected. No per-type config properties.

record

Default constraints: Name-keyed map of embedded sub-objects (Record<string, SubObject>) — ADR-0007. Stored as a JSON object map; insertion order is display order. No per-type config properties.

Enhanced Types

location

Default constraints: Stored as { lat, lng, altitude?, accuracy? } — the keys are lat/lng, not latitude/longitude (LocationValueSchema, ADR-0104 D1). lat: -90 to 90. lng: -180 to 180. No per-type config properties.

address

Default constraints: Stored as structured object with street, city, state, postalCode, country, countryCode, formatted (all parts optional). No per-type config properties.

code

Default constraints: Stored as plain text. Language used for UI syntax highlighting only.

json

Default constraints: Must be valid JSON. Parsed and validated on save.

color

Default constraints: Stores the color value as a string. No per-type config properties.

rating

Default constraints: Integer between 0 and max.

slider

Default constraints: Numeric value between min and max in step increments.

signature

Default constraints: Stored as base64-encoded image data. Immutable after creation in most workflows.

qrcode

Default constraints: Stores the encoded value; rendered as a scannable code. No per-type config properties.

progress

Default constraints: Numeric value rendered as a progress bar. Usually 0–100.

tags

Default constraints: Stored as array of strings. A lone scalar value is coerced into a single-element array; the engine does not trim or deduplicate entries.

AI/ML Types

vector

Default constraints: Must be a numeric array of exactly dimensions length. Set the flat dimensions property directly — the legacy nested vectorConfig object was removed in the 16.x line (#2377) and is no longer part of the schema.

{
  name: 'content_embedding',
  label: 'Content Embedding',
  type: 'vector',
  dimensions: 1536
}

Security & Compliance Properties

For sensitive data, use the properties and types the platform actually enforces:

For reversible encrypted-at-rest values (API keys, tokens, DB passwords), use the secret field type — it is the type with an enforced encryption/masking code path (encrypted at rest via sys_secret, masked on read). password is validated like plain text and stored plaintext at rest with no built-in hashing or encryption; it is masked to •••••••• on read but offers no at-rest protection (see the password section above). See the Field Type Gallery.

Quick Validation Summary