Fields Reference

Overview

Every entity column has a field type (fieldTypeCd) that determines how data is stored, validated, displayed, and edited. The field type is paired with a PostgreSQL data type (dbDatatype) for physical columns.

Column Types

Most columns are physical database columns and don’t need a columnType. Set it only for the special cases below:

columnType	Description
(omitted)	Regular physical database column. Stores a value.
R	Reference — virtual column. Displays a value from a related entity via a foreign key (N:1 lookup). Always paired with a hidden FK column.
S	Set — virtual column. Displays a collection of child records (1:N relationship).
F	Formula — virtual column. Calculated value from an expression. Requires baseDatatypeCd.
G	Generated — physical column auto-maintained by the database.

Text Fields

Field Type	Display Name	Description
text	Text	Single-line text input. Stored as varchar. Use maxLen to set length.
email	Email	Text with email format validation. Stored as varchar.
phone	Phone	Text with phone number format. Stored as varchar.
url	URL	Text displayed as a clickable link. Stored as varchar.
textarea	Multiline Text	Multi-line text area. Stored as text. Configure defaultLines and maxLines in params.
multiline	Rich Text	Rich text content with formatting. Stored as text.

To completely hide a column from the UI, give it empty flags ("") instead of using a hidden field type.

Number Fields

Field Type	Display Name	Description
number	Number	Numeric input. Supports min/max validation via params.
currency	Currency	Number formatted with currency symbol. Set currency param (e.g., “USD”, “EUR”). 2 decimal precision.
percent	Percent	Number displayed with % symbol. 2 decimal precision. Default range 0-100.

Number Params

Configure via column.params:

• min — minimum allowed value
• max — maximum allowed value
• currency — ISO currency code for currency fields (e.g., “USD” displays as $)

Date & Time Fields

Field Type	Display Name	Description
date	Date	Date picker. Stored as date.
datetime	Date & Time	Date and time picker. Stored as timestamp.
time	Time	Time picker. Stored as time.

Boolean Fields

Field Type	Display Name	Description
checkbox	Checkbox	True/false toggle.

Selection Fields

Field Type	Display Name	Description
dropdown	Dropdown	Single selection from a list of options.
flags	Flags	Multi-value selection. Displayed as buttons or checkboxes.
tags	Tags	Free-form or predefined tag input.

Options Configuration

Dropdown and flags options are defined in column.params.options:

{
  "options": ["New", "In Progress", "Completed"]
}

Or with labels, icons, and colors:

{
  "options": [
    { "value": "new", "label": "New", "color": "#3B82F6" },
    { "value": "active", "label": "Active", "color": "#10B981" },
    { "value": "closed", "label": "Closed", "color": "#6B7280" }
  ]
}

Conditional Options (Option Sets)

Options can change based on another field’s value using optionSets:

{
  "optionSets": {
    "condition": "object_type",
    "map": {
      "Entity": ["S", "I", "U", "D", "C"],
      "Action": ["E"],
      "Report": ["E"],
      "*": ["E"]
    }
  }
}

Relationship Fields

Field Type	Display Name	Column Type	Description
lookup	Lookup	R (Reference)	Searchable dropdown that links to another entity. Creates a foreign key relationship.
grid	Detail Grid	S (Set)	Embedded grid showing child records of a 1:N relationship.
user	User Picker	D (Data)	Special lookup that searches the user table.
entitylink	Entity Link	D (Data)	Polymorphic link to any entity type. Stored as JSON.

Lookup Configuration (FK + Reference Pattern)

A lookup needs two columns: a hidden physical foreign key column and a virtual reference column that renders the lookup control.

"account_id": {
  "dbDatatype": "cuid",
  "flags": "EM",
  "orderNum": 30,
  "description": "Account ID"
},
"account": {
  "columnType": "R",
  "fieldTypeCd": "lookup",
  "flags": "VEM",
  "orderNum": 35,
  "description": "Account",
  "link": {
    "entity": "crm.account",
    "thisKey": "account_id",
    "otherKey": "account_id"
  }
}

The hidden FK stores the value; the virtual reference renders the autocomplete and displays the linked record’s toString template.

Media Fields

Field Type	Display Name	Description
image	Image	Image upload with preview.
file	File	File upload with download link.
color	Color Picker	Color selection with hex value storage.

Data Fields

Field Type	Display Name	Description
json	JSON Editor	Structured JSON data with syntax highlighting.

Formula Columns

Formula columns (column type F) calculate values from expressions. They have no physical database column — values are computed at runtime.

Sync Formulas

Evaluated immediately from local record data:

• [quantity] * [unit_price] — multiplies two fields
• [first_name] + ' ' + [last_name] — concatenates strings
• IF([amount] > 1000, 'High', 'Standard') — conditional logic

Async Formulas (Navigation)

Follow reference paths to fetch data from related entities:

• [account_id].[industry] — gets the industry from the linked account
• [order_id].[customer_id].[name] — two-level navigation

Async formulas require a separate data fetch and are resolved after sync formulas.

Formula Requirements

Formula columns must specify:

• baseDatatypeCd — the result type (e.g., “string”, “number”)
• fieldTypeCd — how to display the result
• formula — the expression text

Column Params Reference

All field types support these params via column.params:

Param	Type	Description
options	array	Dropdown/flags options
optionSets	object	Conditional options based on another field
min / max	number	Number validation bounds
currency	string	ISO currency code for currency fields
align	string	Text alignment override (left, center, right)
gridWidth	number	Default column width in grid view
defaultLines	number	Initial textarea height (lines)
maxLines	number	Maximum textarea height (lines)
limWidth	boolean	Limit field width in card/form view

Column Flags

Columns use single-character flags to control behavior. Combine them as a single string (e.g., "VEM").

Flag	Meaning
V	Visible — shown in grid and card views
E	Editable — user can modify the value
M	Mandatory — required for insert (red asterisk in UI)
O	On insert — set only on insert, not editable after
S	Sortable — column can be sorted
G	Groupable — column can be used for grouping
F	Filterable — column appears in the filter row
C	Compact — included in compact/list views

Common combinations:

Combination	Use case
"VEM"	Standard required input field
"VE"	Standard optional input field
"V"	Read-only display (formulas, computed values)
"EM"	Hidden FK column (paired with a Reference)
""	Completely hidden system column

Flags can be overridden per folder, so the same field can be editable in one folder and read-only in another.

Number Sequences

Document entities (invoices, orders, quotes) can auto-generate human-readable numbers on insert. Define a numberSequence at the entity level:

"numberSequence": {
  "column": "invoice_number",
  "prefixSettingCd": "invoice_number_prefix",
  "defaultPrefix": "INV-",
  "pattern": "{prefix}{yyyy}-{seq:3}",
  "resetPeriod": "year"
}

Property	Description
column	Target column to auto-fill on insert
prefixSettingCd	Module setting code for the prefix (folder-scoped, so each branch can use its own prefix)
defaultPrefix	Fallback prefix if the setting isn’t configured
pattern	Format pattern with placeholders
resetPeriod	When the counter resets: year, month, day, or never

Pattern placeholders: {prefix}, {yyyy}, {yy}, {mm}, {dd}, {seq:N} (zero-padded width).

Example output: INV-2026-001, INV-2026-002, …

Constraints

Add CHECK constraints at the entity level for server-side and client-side validation:

"constraints": {
  "chk_amount_positive": {
    "type": "check",
    "expression": "amount IS NULL OR amount >= 0",
    "message": "Amount cannot be negative"
  }
}

Constraints become real PostgreSQL CHECK constraints on the table and are also evaluated client-side via the formula evaluator for immediate UI feedback.

Traits

Traits auto-add common columns. Specify them at the entity level — they apply before your fields, so you can override individual columns if needed.

Trait	Columns added
identity	{entity}_id (int8 primary key, snowflake ID)
audit	created_by, modified_by, created_date, modified_date

"traits": ["identity", "audit"]