Field types — the complete visual gallery

ObjectStack provides a comprehensive set of field types covering every data modeling need — from basic text and numbers to AI vectors and rich media. This guide organizes them by category with per-type configuration details.

Text Types

text

Single-line plain text input.

{ name: 'first_name', label: 'First Name', type: 'text', maxLength: 100 }

textarea

Multi-line text input for longer content.

{ name: 'description', label: 'Description', type: 'textarea', maxLength: 5000 }

email

Email address with built-in format validation.

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

url

URL with format validation.

{ name: 'website', label: 'Website', type: 'url' }

phone

Phone number field.

{ name: 'phone', label: 'Phone', type: 'phone' }

password

Masked password input. On a generic object the value is plaintext at rest but masked to •••••••• on read (ADR-0100) — it is not one-way hashed. One-way hashing is owned by the auth subsystem and applies only to its identity tables, never to an authored password field. For reversible encrypted-at-rest secrets (API keys, tokens, DB passwords), use the secret type instead; for login credentials, model them on the auth user object.

{ name: 'password', label: 'Password', type: 'password', required: true }

secret

Reversible, encrypted-at-rest value (DB password, API key, token). Unlike password (masked on read but plaintext at rest, or one-way hashed inside the auth subsystem), a secret is encrypted on write via the registered crypto provider, stored as an opaque ref on the row, and masked on read. Fail-closed: with no provider configured, writes throw rather than persist cleartext.

{ name: 'api_key', label: 'API Key', type: 'secret' }

Rich Content Types

markdown

Markdown-formatted text with preview support.

{ name: 'readme', label: 'README', type: 'markdown' }

html

Rich HTML content.

{ name: 'body', label: 'Body', type: 'html' }

richtext

WYSIWYG rich text editor content.

{ name: 'content', label: 'Content', type: 'richtext' }

Number Types

number

Numeric value with optional precision.

{ name: 'quantity', label: 'Quantity', type: 'number', min: 0, max: 99999 }

currency

Monetary value. The stored value is a bare number in both modes; the currency code lives in currencyConfig, never in the value.

{ name: 'price', label: 'Price', type: 'currency', currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'USD' } }

A currency amount's decimal places are its currency's ISO 4217 minor unit (2 for USD, 0 for JPY, 3 for KWD), not a field setting, and they are declared nowhere. A currency field takes no scale, and currencyConfig has no decimal-places key: publish-time validation refuses scale on the field and currencyConfig.precision (removed in @objectstack/spec 17.5.0 — no renderer or runtime ever read it), each with a prescription to delete the key. The field-level precision is the amount's total digit count — a DECIMAL(18,2) amount declares precision: 18 — and is never compared with the currency.

percent

Percentage value (0–100 or decimal).

{ name: 'discount', label: 'Discount', type: 'percent', min: 0, max: 100 }

Date & Time Types

date

Date value (no time component).

{ name: 'birth_date', label: 'Birth Date', type: 'date' }

datetime

Date and time value with timezone support.

{ name: 'created_at', label: 'Created At', type: 'datetime', readonly: true }

time

Time-only value (no date component).

{ name: 'start_time', label: 'Start Time', type: 'time' }

Boolean Types

boolean

Standard true/false field.

{ name: 'is_active', label: 'Active', type: 'boolean', defaultValue: true }

toggle

Toggle switch (functionally identical to boolean, different UI).

{ name: 'notifications_enabled', label: 'Notifications', type: 'toggle' }

Selection Types

select

Single-choice dropdown.

SelectOption properties:

{
  name: 'status', label: 'Status', type: 'select',
  options: [
    { label: 'Open', value: 'open', color: 'blue', default: true },
    { label: 'In Progress', value: 'in_progress', color: 'yellow' },
    { label: 'Done', value: 'done', color: 'green' }
  ]
}

multiselect

Multi-choice dropdown. Same options property as select.

{
  name: 'tags', label: 'Tags', type: 'multiselect',
  options: [
    { label: 'Bug', value: 'bug' },
    { label: 'Feature', value: 'feature' },
    { label: 'Enhancement', value: 'enhancement' }
  ]
}

radio

Radio button group (single choice). Same options property as select.

{
  name: 'priority', label: 'Priority', type: 'radio',
  options: [
    { label: 'Low', value: 'low' },
    { label: 'Medium', value: 'medium', default: true },
    { label: 'High', value: 'high' }
  ]
}

checkboxes

Checkbox group (multi-choice). Same options property as select.

{
  name: 'features', label: 'Features', type: 'checkboxes',
  options: [
    { label: 'Email', value: 'email' },
    { label: 'SMS', value: 'sms' },
    { label: 'Push', value: 'push' }
  ]
}

Relational Types

lookup

Reference to a record in another object (foreign key).

{ name: 'company', label: 'Company', type: 'lookup', reference: 'account' }

user

Person picker — a lookup specialized to the built-in sys_user object. Stored identically to lookup (foreign key to sys_user.id; multiple: true stores an array) and resolved through the same $expand machinery. Supports defaultValue: 'current_user' to stamp the acting user's id on insert.

Field.user({ label: 'Assignee' })
Field.user({ label: 'Watchers', multiple: true })
Field.user({ label: 'Owner', defaultValue: 'current_user' })

master_detail

Parent-child relationship (cascading delete by default).

{
  name: 'order',
  label: 'Order',
  type: 'master_detail',
  reference: 'order',
  inlineEdit: true,
  inlineAmountField: 'line_total',
}

tree

Self-referential hierarchy (e.g., categories, org chart).

{ name: 'parent_category', label: 'Parent Category', type: 'tree', reference: 'category' }

Media Types

Media fields store a reference to an uploaded file. They take the universal field properties (multiple is honored for file and image). Two more field properties apply to the media family (file, image, avatar, video and audio) and constrain the referenced file: accept, the permitted upload types as MIME types or extensions (e.g. ["image/*", ".pdf"]), offered to the file picker and enforced on write; and maxSize, the maximum permitted file size in bytes, enforced on write against the stored file size, not just checked in the browser. A create or update whose referenced file violates either is refused with 400 ERR_FILE_CONSTRAINT, and the error message names the field and the constraint. Storage itself is configured at the storage-provider layer, not on the field.

image

Image file with optional validation.

{ name: 'photo', label: 'Photo', type: 'image' }

file

Generic file attachment.

{ name: 'attachment', label: 'Attachment', type: 'file', multiple: true }

avatar

Profile image (typically square, small).

{ name: 'avatar', label: 'Avatar', type: 'avatar' }

video

Video file attachment.

{ name: 'demo_video', label: 'Demo Video', type: 'video' }

audio

Audio file attachment.

{ name: 'recording', label: 'Recording', type: 'audio' }

Computed Types

formula

Calculated field using a CEL expression (see Expressions).

{ name: 'total', label: 'Total', type: 'formula', expression: 'record.quantity * record.unit_price', returnType: 'number' }

summary

Roll-up summary from child records.

{
  name: 'task_count',
  label: 'Task Count',
  type: 'summary',
  summaryOperations: {
    object: 'task',
    field: 'id',
    function: 'count',
    relationshipField: 'project',
  },
}

Add a filter to aggregate only a subset of children — this is how one child object feeds several different totals. The engine ANDs the predicate with the parent-FK match and recomputes on the child's next write, so a row moving in or out of the filter (a status change) keeps the parent current:

// Sum only received receipt lines (3-way match), not every line.
{
  name: 'received_amount',
  type: 'summary',
  summaryOperations: {
    object: 'procurement_receipt',
    field: 'amount',
    function: 'sum',
    filter: { status: 'received' },
  },
}

// One `engagement` child → distinct totals, differentiated only by the filter.
{
  name: 'total_signups',
  type: 'summary',
  summaryOperations: { object: 'engagement', field: 'id', function: 'count', filter: { type: 'signup' } },
}

autonumber

Auto-incrementing number with format template.

{ name: 'ticket_number', label: 'Ticket #', type: 'autonumber', autonumberFormat: 'TKT-{0000}' }

Embedded Structured Types

These types store structured values as JSON on the parent row — no separate table or foreign key.

composite

Single embedded sub-object with declared sub-fields (similar to a Strapi component / ACF group).

{ name: 'dimensions', label: 'Dimensions', type: 'composite' }

repeater

Repeating embedded sub-object array with declared sub-fields (similar to a Strapi repeatable component / ACF repeater).

{ name: 'line_items', label: 'Line Items', type: 'repeater' }

record

Name-keyed map of embedded sub-objects (Record<string, SubObject>). Insertion order is display order. Used for collections where each item has a stable machine name. See ADR-0007.

{ name: 'settings', label: 'Settings', type: 'record' }

Enhanced Types

location

Geographic coordinates. Stored as { lat, lng, altitude?, accuracy? } (lat −90..90, lng −180..180). No per-type config properties. The key names are lat/lng, not latitude/longitude — see LocationValueSchema in field-value.zod.ts (ADR-0104 D1). The schema is strict (#13802): an undeclared key is refused by name, not silently dropped.

{ name: 'headquarters', label: 'Location', type: 'location' }

address

Structured postal address. Stored as { street, city, state, postalCode, country, countryCode, formatted } (all parts optional). No per-type config properties. The schema is strict (#13802): an undeclared key such as postal_code or zipCode is refused with a rename to postalCode, not silently dropped.

{ name: 'billing_address', label: 'Billing Address', type: 'address' }

code

Source code with syntax highlighting.

{ name: 'snippet', label: 'Code Snippet', type: 'code', language: 'typescript' }

json

Raw JSON data.

{ name: 'metadata', label: 'Metadata', type: 'json' }

color

Color picker. Stores the color value as a string. No per-type config properties.

{ name: 'brand_color', label: 'Brand Color', type: 'color' }

rating

Star rating input.

{ name: 'satisfaction', label: 'Rating', type: 'rating', max: 5 }
// or with the factory:
// satisfaction: Field.rating(5, { label: 'Rating' })

slider

Range slider input.

{ name: 'confidence', label: 'Confidence', type: 'slider', min: 0, max: 100, step: 5 }

signature

Digital signature capture.

{ name: 'approval_signature', label: 'Signature', type: 'signature' }

qrcode

QR/barcode value rendered as a scannable code. No per-type config properties.

{ name: 'asset_tag', label: 'Asset Tag', type: 'qrcode' }

progress

Progress bar (0–100).

{ name: 'completion', label: 'Completion', type: 'progress' }

tags

Tag input with autocomplete.

{ name: 'labels', label: 'Labels', type: 'tags' }

AI / ML Types

vector

Vector embeddings for semantic search and similarity.

An earlier nested vectorConfig object was removed — the field builder no longer emits it and it is ignored. Set the flat dimensions property instead.

{ name: 'embedding', label: 'Embedding', type: 'vector', dimensions: 1536 }
// or with the factory:
// embedding: Field.vector(1536, { label: 'Embedding' })

Universal Field Properties

These properties are available on all field types:

Choosing a Field Type

Not sure which type fits your data? Follow the Field Type Decision Tree — a flowchart, quick-reference tables, and a use-case mapping for every type in this gallery.