ObjectStackObjectStack

Field schema — Data Protocol reference

Field schemas of the ObjectStack Data Protocol: CurrencyConfig, CurrencyValue, Field and 7 more — each property with its type, default and a TypeScript example.

Source: packages/spec/src/data/field.zod.ts

TypeScript Usage

import { CurrencyConfigSchema, CurrencyValueSchema, FieldSchema, FieldMaskingKeepSchema, FieldMaskingRuleSchema, FieldType, InlineGridColumnSchema, LocationCoordinatesSchema, SelectOptionSchema, UniqueScopeSchema } from '@objectstack/spec/data';
import type { CurrencyConfig, CurrencyValue, Field, FieldMaskingKeep, FieldMaskingRule, FieldType, InlineGridColumn, LocationCoordinates, SelectOption, UniqueScope } from '@objectstack/spec/data';

// Validate data
const result = CurrencyConfigSchema.parse(data);

CurrencyConfig

Properties

PropertyTypeRequiredDescription
currencyModeEnum<'dynamic' | 'fixed'>optional (default: "dynamic")Currency mode. fixed: the field has one currency, defaultCurrency. dynamic (the default): the field has no currency of its own — amounts display in the tenant default currency (the localization.currency setting; a plain number when none is set) and defaultCurrency is not read. Neither mode is a per-record choice: the value is a bare number either way.
defaultCurrencystringoptional (default: "CNY")The currency code (ISO 4217, e.g. USD, CNY, EUR) of a fixed-mode field: its one currency. Not read under dynamic (the default), where amounts display in the tenant default currency.

CurrencyValue

Properties

PropertyTypeRequiredDescription
valuenumber✅Monetary amount
currencystring✅Currency code (ISO 4217)

Field

Properties

PropertyTypeRequiredDescription
namestringoptionalMachine name (snake_case)
labelstringoptionalHuman readable label
typeEnum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | 'markdown' | 'html' | 'richtext' | 'number' | 'currency' | 'percent' | 'date' | … +35 more>✅Field Data Type
descriptionstringoptionalTooltip/Help text
formatstringoptionalFree-form string whose meaning depends on the field type and on the reader. The spec declares NO vocabulary for it and checks nothing but that it is a string, so any string parses on any field type. On an autonumber field it is the record-number PATTERN — the shorthand that predates autonumberFormat, which wins when both are present: format: 'INV-{0000}' mints INV-0001 on both the query engine and the SQL driver, while a value carrying no {...} token is emitted as literal text with the bare counter appended (format: 'email' mints email1). Prefer autonumberFormat on a new field. On any other field type the server does not act on it: it picks no column type, coerces no value and runs no check from it. The Studio UI reads it as a display hint, in words and with defaults that its renderers own and declare. For example, the date and datetime cells read it as a display STYLE, and on a plain-text field the shared cell-renderer resolver reads a small set of words that promote the cell to a richer renderer, such as a link; each of those falls back silently to a default rendering when it does not recognise the word. To constrain a VALUE, use the field type (the write-time record validator's built-in email, url and phone checks key on type, never on this key) or a format validation rule, whose own format key is the closed set email | url | phone | json.
requiredbooleanoptional (default: false)Write-time contract (ADR-0113): an insert must provide a non-null value, and an update may not null it out. On a multi-value lookup (multiple: true) required means NON-EMPTY array — an emptied required set fails validation loudly; [] does not satisfy it. NOT a column constraint — the physical NOT NULL is a separate explicit opt-in (storage.notNull), so tightening this on a deployed object is safe: existing null rows stay readable, and editable as long as the write does not touch this field.
storage{ notNull?: boolean }optionalPhysical storage constraints (ADR-0113). Owns the DDL the write contract deliberately does not imply. Absent = no storage-level constraint requested.
searchablebooleanoptional (default: false)Is searchable
multiplebooleanoptional (default: false)Allow multiple values (Stores as Array/JSON). Declarable ONLY on the multi-capable types — select, lookup, user, file, image — and redundantly on the inherently-multi option types (multiselect, checkboxes, tags); multiple: true on any other type, radio included, is REFUSED at parse. An emptied multi-value lookup reads back as [], never null — the rule binds every writer (cascade repair, form clears, API writes), not just cascade repair.
uniqueboolean | 'global' | 'organization'optionalUnique constraint and its scope (ADR-0120). 'organization' = one holder per organization (NULL-safe composite with the organization key part on organization-scoped objects) — prefer this explicit spelling in new code; true = same per-organization scope (positional synonym, stays valid); 'global' = one holder across the whole installation. 'tenant'/'org' are rejected — the word is 'organization'. Omitted ⇒ false, EXCEPT on an autonumber field, where omitted ⇒ 'organization' (an auto-number is a business identifier, so the platform makes it unique per organization by default — the same tenant-composite shape an explicit unique: true produces). To opt an autonumber field out, write unique: false explicitly — legitimate only for a display-only sequence that is not used to identify the record; the platform's duplicate scan (os migrate duplicates) still treats every autonumber field as an identifier.
defaultValueanyoptionalDefault applied on INSERT when the field is omitted or null ('' is a real value, not absence). Three legal shapes, discriminated in the engine's own order: a CEL Expression envelope { dialect: 'cel', source: 'today()' } (accepted structurally; result type is a runtime concern); a runtime TOKEN — NOW() on datetime/date/time only, current_user on user or lookup with reference: 'sys_user' only, neither on a multi-value field; or a LITERAL, which must satisfy this field's own stored value contract (ADR-0104 D1 valueSchemaFor). Anything else is refused at parse time with a prescriptive message.
maxLengthintegeroptionalMax character length (positive integer). Only authorable on types that store a bounded string: text, textarea, email, url, phone, password, markdown, html, richtext, code, signature, qrcode. Checked on the WRITTEN value only (the min/max transition-gate class): a stored value longer than a bound declared later is never re-read and survives unrelated edits — only a write carrying an over-long value is refused.
minLengthintegeroptionalMin character length (positive integer; minLength: 0 is refused — express "no minimum" by omitting the key). Only authorable on types that store a bounded string: text, textarea, email, url, phone, password, markdown, html, richtext, code, signature, qrcode. Checked on the WRITTEN value only (the min/max transition-gate class): a stored value shorter than a bound declared later is never re-read and survives unrelated edits — only a write carrying a too-short value is refused.
valueDomainEnum<'iana_time_zone' | 'iso_4217_currency' | 'iso_3166_alpha2'>optionalStandard value domain the WRITTEN value must be a member of: iana_time_zone (an IANA/tzdb zone identifier such as UTC, Asia/Kolkata, Europe/Kyiv — membership is the Intl.DateTimeFormat probe, never the Intl.supportedValuesOf enumeration, which omits UTC), iso_4217_currency (an ISO 4217 alphabetic currency code, uppercase, e.g. CHF) or iso_3166_alpha2 (an ISO 3166-1 alpha-2 country code, uppercase, e.g. CH). The same closed vocabulary and the same membership predicate as a settings specifier's valueDomain. Only authorable on text — the one type whose stored value is a single plain string naming the member. Checked on the WRITTEN value only (the min/max/maxLength transition-gate class): a stored value outside a domain declared later is never re-read and survives unrelated edits — only a write carrying a non-member is refused, with the field error code value_domain. Reach for it precisely where a pattern cannot help: ^[A-Z]{2}$ admits ZZ, and Mars/Olympus is a shape-valid zone that does not exist.
rowsintegeroptionalHeight of the INLINE multiline editor, in text rows (positive integer — the HTML textarea rows attribute; fullscreen/dialog editor surfaces size themselves and ignore it). Only authorable on multiline editor types: textarea, markdown, html, richtext. Omit it for the widget default height.
precisionintegeroptionalTotal digits (non-negative integer) — the p of a DECIMAL(p, s): the digits of the value, integer and fraction together, counted at the field's decimal places, so precision: 5, scale: 2 holds up to 999.99 and refuses 1234.5 (1234.50 is 6 digits). Enforced on writes of number, currency, percent, rating and slider fields: a value that needs more digits is refused with field code max_precision, never rounded. Counted on the STORED value: at the declared scale when one applies, else at the value's own decimal places (leading zeros never count) — so on a currency field, where scale is refused, an amount's written decimals count toward the total; a fraction-stored percent is counted two places further right (scale + 2, or 2 with no scale), which makes the count that of the percentage-point value as displayed. Not decimal places (that is scale; a currency's are its ISO 4217 minor unit) and not a column size: every numeric column keeps the platform's fixed exact decimal whatever this declares. Not read on any other field type.
scaleintegeroptionalDecimal places (integer 0-100). Applies to number, percent, rating and slider fields, where it is enforced on writes, and to a formula field, whose computed result is rounded to it. REFUSED on a currency field — delete it there: a currency amount's decimal places are its currency's, so the currency's ISO 4217 minor unit decides how the amount displays, and a currency write's decimal places stay unconstrained. OMITTED on a percent field ⇒ 0 decimal places, so a stored 0.25 reads 25% on every face; omitted on any OTHER numeric type declares NO fixed width — the value keeps its natural precision, and a DECLARED scale: 0 (a year, a fiscal period, an ordinal) stays distinguishable from having declared nothing, so nothing is defaulted there. Consumers resolve the effective width by calling resolveFieldScale from @objectstack/spec/data, the single source for an absent scale: a renderer that spells its own fallback is a width no other face can see, and that is how one stored 0.25 came to read 25% on the read-only cell and 25.00% in the edit widget. On a percent field this is the number of decimal places of the PERCENTAGE-POINT value as displayed and entered — scale: 2 means 12.34% — and the STORED precision derives from the field's storage scale rather than being declared again: a fraction-stored percent (no max, or a max at or below 1) stores 12.34% as 0.1234 and is allowed scale + 2 decimal places at the write seam, while a whole-percent field (max above 1) stores the displayed number itself and is allowed exactly scale. number, rating and slider are allowed exactly scale. The upper bound is the platform's, not a policy: renderers turn scale into fraction digits through toFixed and Intl.NumberFormat's maximumFractionDigits, both of which throw a RangeError above 100 — so a larger declaration is unrenderable by any conforming consumer.
minnumberoptionalMinimum value. Checked on the WRITTEN value only — the same transition-gate class as requiredWhen: an UPDATE validates just the fields the payload carries, so a stored value below a bound declared later is never re-read and survives unrelated edits; only a write that carries an out-of-bound value is refused, and a repairing write is accepted. For an invariant re-checked on every write, declare a validations[] script rule instead.
maxnumberoptionalMaximum value. Checked on the WRITTEN value only — the same transition-gate class as min: a stored value above a bound declared later is never re-read and survives unrelated edits; only a write that carries an out-of-bound value is refused. For an invariant re-checked on every write, declare a validations[] script rule instead.
useGroupingbooleanoptionalDigit-grouping presentation hint for number fields — maps to Intl.NumberFormat's useGrouping. Absent = renderer decides (interim heuristic today, locale default eventually); false = author opts out of grouping (e.g. a year or other ordinal/identifier integer); true = author pins grouping on.
acceptstring[]optionalPermitted upload types for media fields, as MIME types or extensions (e.g. ["image/*", ".pdf"]). Offered to the file picker AND enforced on write.
maxSizeintegeroptionalMaximum permitted file size in BYTES for media fields. Enforced on write against the stored file size, not just checked in the browser.
options{ label: string; value: string; description?: string; color?: string; … }[]optionalStatic options for the option types. A select / radio field needs a non-empty list here or a picklist — with neither (or options: []) it is refused at parse.
pickliststringoptionalName of a shared picklist whose options this field offers — instead of options, never with it. Option types only (select, radio, multiselect, checkboxes, tags). A select / radio declares this or a non-empty options; with neither it is refused at parse.
referencestringoptionalTarget object name (snake_case) for lookup/master_detail fields. Required for relationship types. Used by $expand to resolve foreign key IDs into full objects. On a tree field it is optional and, if given, must be the declaring object's own name — the object schema refuses any other target, and writes the own name when it is left out.
referenceViastringoptionalDeclares this text field as the id half of a polymorphic pointer pair (ADR-0052 §5 ActivityPointer): the value is a record id of the object named by the SIBLING FIELD this key names — e.g. record_id with referenceVia: 'object_name'. The sibling must be a declared field on the same object holding an object machine name. Text fields only; mutually exclusive with reference (a static and a per-record target contradict). Enforced today at seed load: the value resolves as a natural key against the object the sibling column names, and an unresolvable pointer is refused loudly instead of stored verbatim. Adds no referential integrity or $expand behavior.
referenceDeletedWhen{ field: string; value: string }optionalMarks the record a referenceVia pointer names as PLATFORM-DELETED on rows where a sibling select field holds one declared option — e.g. record_id with { field: 'cancel_reason', value: 'record_deleted' }. A renderer then draws a tombstone from that option's own label, reads nothing and links nothing. Valid only beside referenceVia; field must be a single-value select on the same object declaring inline options, and value one of its option values — any other shape is refused at parse.
mailAssociationbooleanoptionalInbound mail association (email fields only): TRUE marks this field as identifying a correspondent. When a mailbox service ingests a message, it associates the message with every record of this object whose value in this field equals one of the message's participant addresses (From, Sender, Reply-To, To and Cc, plus those of a forwarded message it carries; ASCII case-insensitive; the receiving mailbox's own addresses excluded; only within the mailbox's organization). A message no record matches waits in the mailbox's unassociated pool. Refused on any other type. Takes effect only where a mailbox service is composed.
deleteBehaviorEnum<'set_null' | 'cascade' | 'restrict'>optional (default: "set_null")What happens if referenced record is deleted
inlineEditboolean | Enum<'grid' | 'form'>optionalEdit these child records inline within the parent's form (atomic master-detail). true = auto-pick grid/form by child shape; 'grid' = editable line-item grid; 'form' = list + per-row full form.
inlineTitlestringoptionalTitle for the inline master-detail grid
inlineColumns{ name: string; label?: string; type?: Enum<'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file'>; width?: number; … }[]optionalExplicit columns for the inline grid (derived from the child object when omitted). Each entry is a strict, name-keyed column ({ name, label?, type?, … } — objectui GridColumn); identity-only entries ({ name }) hydrate everything else from the child object's fields. Unknown keys and the retired field spelling are refused at parse.
inlineAmountFieldstringoptionalNumeric child field summed for the inline grid total
relatedListboolean | 'primary'optionalShow this child collection as a related list on the parent's detail page (read-side mirror of inlineEdit). false = suppress; true/absent = shown (stacked under the shared "Related" tab); 'primary' = core relationship, promoted to its own tab. Prominence intent, not a layout switch (ADR-0085). A derived related list (relatedList: 'primary') inherits its row order from the child object's DEFAULT list view sort — the isDefault view, or the first declared list item when none is marked default; wire spelling is sort=<field> / sort=-<field>, never $orderby. A child object with no list-view sort emits no ordering parameter, and rows fall back to record-id order.
relatedListTitlestringoptionalTitle for the detail-page related list
relatedListColumnsstring[]optionalExplicit columns for the detail-page related list, as child field names (e.g. ['name', 'status']); derived from the child object (highlightFields → field walk) when omitted. Strings only — labels, cell types and formatting always derive from the child object's field definitions; column objects are refused at parse.
relatedListFilteranyoptionalDeclarative default filter for the detail-page related list: AND-composed with the parent-relationship condition { [referenceField]: parentId } — an authored constraint, never a user-editable suggestion. The related-list tab badge count honors the same composed filter, so counts match the visible rows. Canonical Query-DSL FilterCondition (the same dialect as a query where), e.g. { status: { $ne: 'deleted' } } to hide soft-deleted children.
displayFieldstringoptionalField shown as each candidate's label in the picker/popover (defaults to the referenced object's name/title).
descriptionFieldstringoptionalSecondary field shown under the label in the quick-select popover.
lookupColumns(string | { field: string; label?: string; width?: string; type?: string })[]optionalExplicit columns for the record-picker table; auto-derived from the referenced object when omitted.
lookupPageSizeintegeroptionalRows per page in the record-picker dialog (default 10).
lookupFilters{ field: string; operator: Enum<'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'in' | 'notIn'>; value: any }[]optionalBase filters restricting which records are selectable (e.g. only active). The structured, picker-honoured lookup filter.
dependsOn(string | { field: string; param?: string })[]optionalDeclares that this field's available values depend on the value of other field(s) on the same record — the form gates the field until they are set and re-evaluates as they change. For lookup/master_detail it scopes the candidate query (string = same local/remote key; {field,param} when the remote filter key differs — the {field,param} form is lookup-only). For select/multiselect/radio the actual per-option rule lives in each option's visibleWhen; list the referenced fields here (string form) so the option list gates and refreshes with the parent.
allowCreatebooleanoptionalAllow inline quick-create from the record picker: when no match exists the user can create a record from the typed text (optimistic dataSource.create with the display field). Best for simple objects whose only required field is the display field.
expressionstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalFormula expression (CEL). e.g. Frecord.amount * 0.1
returnTypeEnum<'number' | 'text' | 'boolean' | 'date' | 'currency'>optionalInferred value type of a formula field (number/text/boolean/date/currency). currency: an amount of money, in the currency the formula's own currencyConfig declares, as a currency field declares it (no currencyConfig: dynamic, the tenant default currency).
summaryOperations{ object: string; field: string; function: Enum<'count' | 'sum' | 'min' | 'max' | 'avg'>; relationshipField?: string; … }optionalRoll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted.
languagestringoptionalProgramming language for syntax highlighting (e.g., javascript, python, sql)
stepnumberoptionalStep increment for slider (default: 1)
currencyConfig{ currencyMode?: Enum<'dynamic' | 'fixed'>; defaultCurrency?: string }optionalWhich currency an amount is in: for a currency field, and for a formula field whose returnType is currency. Absent: dynamic mode.
dimensionsintegeroptionalVector dimensionality (e.g., 1536 for OpenAI embeddings)
trackHistorybooleanoptionalRender this field's value changes as human-readable entries on the record activity timeline (ADR-0052 §5b). Opt-in per field.
groupstringoptionalField group name for organizing fields in forms and layouts (e.g., "contact_info", "billing", "system")
visibleWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — field is shown only when TRUE (else hidden). e.g. Precord.type == 'invoice'
readonlyWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — field is read-only when TRUE. e.g. Precord.status == 'paid'. Reads the bound record's OWN columns: the field level never reads a related record, so a read THROUGH a reference field (record.account.tier) faults on every row and refuses every update that writes the field — objectstack validate refuses it. Put such a check in a validations[] script rule, whose condition is read one hop through a reference.
requiredWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — field is required when TRUE. A TRANSITION GATE, not an invariant: the write is refused only when the merged record violates the requirement AND the pre-write record complied — so the write that flips the predicate TRUE, an INSERT born inside the gate, and a write that clears the cell are all refused, while a row that was already missing the value keeps passing unrelated edits and state moves that stay inside the gate (ADR-0113 non-regression: adding the rule to a deployed object never bricks existing rows). Need an invariant every write must satisfy instead ('X may never exceed Y') — declare a validations[] script rule, which re-checks the merged record with no exemption. Enforced by evaluateValidationRules. Reads the bound record's OWN columns: the field level never reads a related record, so a read THROUGH a reference field (record.account.tier) faults on every row and refuses every write that reaches it — objectstack validate refuses it; put such a check in a validations[] script rule, whose condition is read one hop through a reference. The only slot; the conditionalRequired alias was removed in protocol 17.
conditionalRequiredneveroptional[REMOVED] conditionalRequired was removed in @objectstack/spec 17 — use requiredWhen. Rename the key; the value (a CEL predicate) is unchanged. Run os migrate meta --from 16 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand.
dueLikebooleanoptionalDeadline semantic (date / datetime only): TRUE declares this date a deadline, so a renderer may show relative overdue wording ("Overdue 3d") and an overdue colour once it has passed. Absent or FALSE: not a deadline — nothing is inferred from the field's name. Pair with settledWhen to say when the deadline is settled for a record. Refused on any other type. Display only: nothing on the write path reads it.
settledWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — the deadline is SETTLED while TRUE: no overdue wording or colour applies to this record, e.g. Precord.status == 'done'. Evaluated per record like visibleWhen, reading the record's own columns as record. Requires dueLike: true on a date / datetime field; refused otherwise. Display only: nothing on the write path reads it.
conditionalFormatting{ condition: string | object; style: Record<string, string> }[]optionalCell formatting rules for this field — [{ condition, style }], the same rule a list view's conditionalFormatting declares. In order, the first rule whose CEL condition holds applies its CSS style map to THIS FIELD'S CELL wherever the field renders (grid, kanban card, record page, related list, report cell); a list view's row rules style the row, and both may apply. The condition reads value (this field's value on the record) and record (the row) and no other root, e.g. Pvalue < 0 with style: { color: '#b91c1c' }; objectstack validate refuses a condition that does not parse or reads any other root. For presentation only — a semantic state such as a deadline's overdue is declared with dueLike / settledWhen instead. Display only: nothing on the write path reads it.
widgetstringoptionalForm widget override — names a registered field component (resolved as field:<widget>) to render this field instead of the type default. Degrades to the type renderer when unregistered. e.g. "object-ref", "filter-condition", "recipient-picker".
hiddenbooleanoptional (default: false)Hidden from default UI
internalbooleanoptionalNever return this field's value on the generic data path — the engine OMITS the key from find/findOne results, the 201 create body and the by-id update body, on the default projection AND when a client names the field in ?select=. Storage, filtering and indexing are untouched, so a server-side verifier can still match on the column and a purpose-built mint route can still return the value once at creation. The read protection for ADR-0100's third credential channel (auth-subsystem one-way hashes on text columns). Omission, not masking: a mask signals 'a value is set', which carries no information on a required column.
readonlybooleanoptional (default: false)Read-only — never editable in forms, AND server-enforced on BOTH write paths: a non-system write to this field is silently dropped from the payload on UPDATE and on INSERT (a create can no longer directly seed e.g. approval_status: "approved"), symmetric with readonlyWhen. A stripped INSERT field still falls back to its defaultValue. Exempt from the strip on BOTH paths: isSystem writes (seed replay, migration). Exempt on the UPDATE path ONLY: an opt-in "historical" import (preserveAudit) — which admits a whitelist (the audit/timestamp family plus author-declared business readonly fields). On INSERT the exemption does NOT apply: a non-system create that requests preserveAudit still has its readonly fields stripped, and is warned loudly that the exemption is UPDATE-only — replaying archival readonly facts on create requires a system context. A normal (non-system) import is NOT system-context and still strips.
requiredPermissionsstring[]optional[ADR-0066 D3] Capabilities required to read/edit this field (mask on read, deny on write; AND-gate).
maskingRuleEnum<'phone' | 'id_card' | 'bank_account' | 'email' | 'name'> | { keepHead: integer; keepTail: integer }optionalPartial masking rule enforced by the runtime FieldMasker (single channel — API, UI, export and AI context all see the same masked value). A named preset ('phone' 138**5678, 'id_card' keep 6+4, 'bank_account' keep last 4, 'email' j*@example.com, 'name' keep first char) or { keepHead, keepTail }. Masked for every non-system caller unless the field's requiredPermissions are ALL held (that evaluation is the unmask gate); a permission set marking the field non-readable still deletes it entirely. Deterministic, length-preserving output; masked callers cannot filter/sort/group/aggregate on the field.
ackPlaintextMaskingbooleanoptional[ADR-0100] Affirm a generic password field's plaintext-at-rest / masked-on-read contract is intended, silencing the author-time warning. No effect on non-password fields.
systembooleanoptionalAuto-injected system/audit field (e.g. created_at, updated_by, organization_id). Tools that surface system fields separately from author-declared business fields should branch on this flag.
sortablebooleanoptional (default: true)Whether field is sortable in list views
inlineHelpTextstringoptionalHelp text displayed below the field in forms
placeholderstringoptionalPlaceholder text rendered inside the empty input (the HTML placeholder attribute); disappears once a value is entered. Distinct from inlineHelpText (always-visible help rendered beside/under the input) and description (tooltip/developer documentation).
autonumberFormatstringoptional (default: "{0000}")Auto-number format: literal text + {0000} counter, {YYYY}/{MM}/{DD}/{YYYYMMDD} date tokens (business tz), and {field_name} interpolation. Counter resets per rendered prefix (e.g. AD{YYYYMMDD}``{0000} resets daily). Omitted on an autonumber field ⇒ the contract default {0000}, which every driver and the engine fallback read, so one field numbers alike on every backend.
externalIdbooleanoptional (default: false)Is external ID for upsert operations
_lockEnum<'none' | 'no-overlay' | 'no-delete' | 'full'>optionalItem-level lock — controls overlay & delete (ADR-0010).
_lockReasonstringoptionalHuman-readable reason shown when a write is refused by _lock.
_lockSourceEnum<'artifact' | 'package' | 'env-forced'>optionalLayer that set _lock (artifact | package | env-forced).
_provenanceEnum<'package' | 'org' | 'env-forced'>optionalOrigin of the item (package | org | env-forced).
_packageIdstringoptionalOwning package machine id.
_packageVersionstringoptionalOwning package version.
_lockDocsUrlstringoptionalOptional documentation link surfaced next to _lockReason.

Allowed Values: Field.type

  • text
  • textarea
  • email
  • url
  • phone
  • password
  • secret
  • markdown
  • html
  • richtext
  • number
  • currency
  • percent
  • date
  • datetime
  • time
  • boolean
  • toggle
  • select
  • multiselect
  • radio
  • checkboxes
  • lookup
  • master_detail
  • tree
  • user
  • image
  • file
  • avatar
  • video
  • audio
  • formula
  • summary
  • autonumber
  • composite
  • repeater
  • record
  • location
  • address
  • code
  • json
  • color
  • rating
  • slider
  • signature
  • qrcode
  • progress
  • tags
  • vector

Nested Shape: Field.storage

PropertyTypeRequiredDescription
notNullbooleanoptionalEmit a physical NOT NULL on the column (ADR-0113). Absent = the column stays nullable even under required: true — the write contract is enforced at the engine, the only sanctioned write path, not by the database. Declaring this over existing null rows is a destructive migration gated by the schema-drift ceremony. Incompatible with requiredWhen (a conditional contract cannot be an unconditional column constraint).

Nested Shape: Field.options[number]

PropertyTypeRequiredDescription
labelstring✅Display label (human-readable, any case allowed)
valuestring✅Stored value (lowercase machine identifier)
descriptionstringoptionalOptional secondary/help text for this option. Lookup option search matches it in addition to the label; renderers may show it as supporting text.
colorstringoptionalColor code for badges/charts
defaultbooleanoptionalIs default option
visibleWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPer-option visibility predicate (CEL) — option is offered only when TRUE (else omitted). Env: the live record plus the host predicate scope, which binds current_user. The one VISIBILITY predicate the SERVER also enforces — the rule validator refuses a write of a value whose predicate is false, or cannot be evaluated — so a user-gated CHOICE belongs here. e.g. Precord.country == 'cn' or P'admin' in current_user.positions. On an OBJECT field's option it reads the record's OWN columns: the server never reads a related record there, so a read THROUGH a reference field (record.account.tier) would fault and every write picking the option would be refused, and objectstack validate refuses it — enforce such a restriction with a validations[] script rule, whose condition is read one hop through a reference.

Nested Shape: Field.referenceDeletedWhen

PropertyTypeRequiredDescription
fieldstring✅The SIBLING select field on the same object whose value marks the target as deleted (snake_case).
valuestring✅The option value of that select field that means "the referenced record was deleted by the platform".

Nested Shape: Field.inlineColumns[number]

PropertyTypeRequiredDescription
namestring✅Child field this column shows — the key the grid reads and writes on each row object (objectui GridColumn.name). The retired field spelling is refused.
labelstringoptionalColumn header; defaults to the child field's label via hydration.
typeEnum<'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file'>optionalCell control, derived from the child field's type when omitted. Declaring it opts the column out of schema hydration — supply the extras (options / reference / …) yourself.
widthnumberoptionalFixed column width in px; omitted columns use type-based role sizing (text flexes, numeric/date/select stay fixed).
requiredbooleanoptionalCell is flagged inline-invalid while empty. Computed columns are never required.
options{ label: string; value: string }[]optionalSelect-cell options for type: 'select'; derived from the child field's options when the column declares no type.
prefixstringoptionalSymbol shown in a currency cell in place of the resolved currency's own symbol. No default: when omitted, the cell shows the symbol of the currency it resolves. It replaces the symbol only — the amount's decimal places stay the currency's.
stepnumberoptionalInput step for numeric cells.
referencestringoptionalReferenced object for type: 'lookup' cells; derived from the child lookup field when the column declares no type.
displayFieldstringoptionalLabel field shown for a picked lookup record.
idFieldstringoptionalId field stored for a picked lookup record.
multiplebooleanoptionalMulti-value column: multi-record lookup, or multi-file upload cell.
acceptstring[]optionalAccepted MIME types / extensions for a file cell's picker (e.g. ['image/*', '.pdf']); omit to accept anything.
defaultHiddenbooleanoptionalCollapsed into the grid's column chooser by default (not dropped); required columns are never default-hidden.
computedbooleanoptionalRead-only computed column, recomputed live from sibling cells via expr and written back into the row.
exprstringoptionalArithmetic expression for a computed column — a BARE string over + - * / %, parentheses, numeric literals and field refs (record.qty or qty), evaluated by the grid's own safe evaluator. Deliberately NOT a CEL Expression envelope; { dialect, source } is refused here.
scaleintegeroptionalDecimal places to round a computed numeric result to (integer 0-100). REFUSED on a column declaring type: 'currency' — delete it there: the currency's ISO 4217 minor unit decides. The upper bound is the renderer's: the grid rounds with toFixed, which throws a RangeError above 100.
autofillbooleanoptionalFor lookup columns: picking a record copies its same-named fields into sibling columns (a product's unit_price/description). On by default; set false to disable.
readonlyWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — the cell is read-only when TRUE, evaluated per row against the row as record plus the header as parent (e.g. Pparent.status == 'paid').
requiredWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — the cell is required when TRUE. Same record + parent scope as readonlyWhen. PRESENTATION ONLY: this flags the cell inline-invalid in the grid; nothing on the write path reads it. The server-enforced contract is the child FIELD's own requiredWhen — a transition gate, see Field.requiredWhen — which hydration copies onto an identity-only column, so declaring the requirement here alone enforces nothing.

Nested Shape: Field.summaryOperations

PropertyTypeRequiredDescription
objectstring✅Source child object name for roll-up
fieldstring✅Field on child object to aggregate (ignored for count)
functionEnum<'count' | 'sum' | 'min' | 'max' | 'avg'>✅Aggregation function to apply
relationshipFieldstringoptionalFK field on the child pointing back to this parent. Auto-detected from the child's lookup/master_detail field referencing this object when omitted; set explicitly only when the child has more than one such reference.
filteranyoptionalPredicate restricting which child rows are aggregated (a query where FilterCondition, e.g. { status: 'received' } or { type: { $in: ['signup','trial'] } }). Omit to aggregate all children. Lets one child object feed multiple filtered roll-ups.

Nested Shape: Field.currencyConfig

PropertyTypeRequiredDescription
currencyModeEnum<'dynamic' | 'fixed'>optional (default: "dynamic")Currency mode. fixed: the field has one currency, defaultCurrency. dynamic (the default): the field has no currency of its own — amounts display in the tenant default currency (the localization.currency setting; a plain number when none is set) and defaultCurrency is not read. Neither mode is a per-record choice: the value is a bare number either way.
defaultCurrencystringoptional (default: "CNY")The currency code (ISO 4217, e.g. USD, CNY, EUR) of a fixed-mode field: its one currency. Not read under dynamic (the default), where amounts display in the tenant default currency.

Nested Shape: Field.conditionalFormatting[number]

PropertyTypeRequiredDescription
conditionstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }✅Predicate (CEL) to evaluate.
styleRecord<string, string>✅CSS styles to apply when condition is true

Nested Shape: Field.maskingRule

PropertyTypeRequiredDescription
keepHeadinteger✅Number of leading characters to leave readable
keepTailinteger✅Number of trailing characters to leave readable

FieldMaskingKeep

Properties

PropertyTypeRequiredDescription
keepHeadinteger✅Number of leading characters to leave readable
keepTailinteger✅Number of trailing characters to leave readable

FieldMaskingRule

Union Options

This schema accepts one of the following structures:

Option 1

Allowed Values: phone, id_card, bank_account, email, name


Option 2

Properties

PropertyTypeRequiredDescription
keepHeadinteger✅Number of leading characters to leave readable
keepTailinteger✅Number of trailing characters to leave readable


FieldType

Allowed Values

  • text
  • textarea
  • email
  • url
  • phone
  • password
  • secret
  • markdown
  • html
  • richtext
  • number
  • currency
  • percent
  • date
  • datetime
  • time
  • boolean
  • toggle
  • select
  • multiselect
  • radio
  • checkboxes
  • lookup
  • master_detail
  • tree
  • user
  • image
  • file
  • avatar
  • video
  • audio
  • formula
  • summary
  • autonumber
  • composite
  • repeater
  • record
  • location
  • address
  • code
  • json
  • color
  • rating
  • slider
  • signature
  • qrcode
  • progress
  • tags
  • vector

InlineGridColumn

Properties

PropertyTypeRequiredDescription
namestring✅Child field this column shows — the key the grid reads and writes on each row object (objectui GridColumn.name). The retired field spelling is refused.
labelstringoptionalColumn header; defaults to the child field's label via hydration.
typeEnum<'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file'>optionalCell control, derived from the child field's type when omitted. Declaring it opts the column out of schema hydration — supply the extras (options / reference / …) yourself.
widthnumberoptionalFixed column width in px; omitted columns use type-based role sizing (text flexes, numeric/date/select stay fixed).
requiredbooleanoptionalCell is flagged inline-invalid while empty. Computed columns are never required.
options{ label: string; value: string }[]optionalSelect-cell options for type: 'select'; derived from the child field's options when the column declares no type.
prefixstringoptionalSymbol shown in a currency cell in place of the resolved currency's own symbol. No default: when omitted, the cell shows the symbol of the currency it resolves. It replaces the symbol only — the amount's decimal places stay the currency's.
stepnumberoptionalInput step for numeric cells.
referencestringoptionalReferenced object for type: 'lookup' cells; derived from the child lookup field when the column declares no type.
displayFieldstringoptionalLabel field shown for a picked lookup record.
idFieldstringoptionalId field stored for a picked lookup record.
multiplebooleanoptionalMulti-value column: multi-record lookup, or multi-file upload cell.
acceptstring[]optionalAccepted MIME types / extensions for a file cell's picker (e.g. ['image/*', '.pdf']); omit to accept anything.
defaultHiddenbooleanoptionalCollapsed into the grid's column chooser by default (not dropped); required columns are never default-hidden.
computedbooleanoptionalRead-only computed column, recomputed live from sibling cells via expr and written back into the row.
exprstringoptionalArithmetic expression for a computed column — a BARE string over + - * / %, parentheses, numeric literals and field refs (record.qty or qty), evaluated by the grid's own safe evaluator. Deliberately NOT a CEL Expression envelope; { dialect, source } is refused here.
scaleintegeroptionalDecimal places to round a computed numeric result to (integer 0-100). REFUSED on a column declaring type: 'currency' — delete it there: the currency's ISO 4217 minor unit decides. The upper bound is the renderer's: the grid rounds with toFixed, which throws a RangeError above 100.
autofillbooleanoptionalFor lookup columns: picking a record copies its same-named fields into sibling columns (a product's unit_price/description). On by default; set false to disable.
readonlyWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — the cell is read-only when TRUE, evaluated per row against the row as record plus the header as parent (e.g. Pparent.status == 'paid').
requiredWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — the cell is required when TRUE. Same record + parent scope as readonlyWhen. PRESENTATION ONLY: this flags the cell inline-invalid in the grid; nothing on the write path reads it. The server-enforced contract is the child FIELD's own requiredWhen — a transition gate, see Field.requiredWhen — which hydration copies onto an identity-only column, so declaring the requirement here alone enforces nothing.

Nested Shape: InlineGridColumn.options[number]

PropertyTypeRequiredDescription
labelstring✅Option label shown in the select cell.
valuestring✅Stored option value; must match the child select field's option values.

LocationCoordinates

Properties

PropertyTypeRequiredDescription
latitudenumber✅Latitude coordinate
longitudenumber✅Longitude coordinate
altitudenumberoptionalAltitude in meters
accuracynumberoptionalAccuracy in meters

SelectOption

Properties

PropertyTypeRequiredDescription
labelstring✅Display label (human-readable, any case allowed)
valuestring✅Stored value (lowercase machine identifier)
descriptionstringoptionalOptional secondary/help text for this option. Lookup option search matches it in addition to the label; renderers may show it as supporting text.
colorstringoptionalColor code for badges/charts
defaultbooleanoptionalIs default option
visibleWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPer-option visibility predicate (CEL) — option is offered only when TRUE (else omitted). Env: the live record plus the host predicate scope, which binds current_user. The one VISIBILITY predicate the SERVER also enforces — the rule validator refuses a write of a value whose predicate is false, or cannot be evaluated — so a user-gated CHOICE belongs here. e.g. Precord.country == 'cn' or P'admin' in current_user.positions. On an OBJECT field's option it reads the record's OWN columns: the server never reads a related record there, so a read THROUGH a reference field (record.account.tier) would fault and every write picking the option would be refused, and objectstack validate refuses it — enforce such a restriction with a validations[] script rule, whose condition is read one hop through a reference.

UniqueScope

Union Options

This schema accepts one of the following structures:

Option 1

Type: boolean


Option 2

Type: 'global'


Option 3

Type: 'organization'



On this page