Skip to content

Latest commit

 

History

History
460 lines (370 loc) · 54.5 KB

field.mdx

File metadata and controls

460 lines (370 loc) · 54.5 KB
title Field schema — Data Protocol reference
navTitle Field
description Field schemas of the ObjectStack Data Protocol: CurrencyConfig, Field and 7 more — each property with its type, default and a TypeScript example.

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

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

TypeScript Usage

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

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

CurrencyConfig

Properties

Property Type Required Description
currencyMode Enum<'dynamic' | 'fixed' | 'record'> 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. record: each record has its own currency, the ISO 4217 code stored in the sibling field currencyField names; defaultCurrency is refused. The value is a bare number in every mode (ADR-0104 D1).
defaultCurrency string optional The currency code (ISO 4217, e.g. USD, CNY, EUR) of a fixed-mode field: its one currency, required under fixed. Not read under dynamic (the default), where amounts display in the tenant default currency, and refused under record, where each record names its own.
currencyField string optional record mode only, and required there: the name of the field on the same object that holds each record's currency — a text field declaring valueDomain: 'iso_4217_currency' (conventionally currency_code). Refused under dynamic and fixed, and never empty.
homeAmount { field: string; rateDate: string; rateField: string } optional record mode only, optional: where the engine stores this amount converted into the organization's home currency (the localization.currency setting) at write, at the rate of the record's document date, and the rate it used. field names a dynamic-mode currency field, rateDate a date / datetime field and rateField a number field, all on the same object; all three are required, and the home and rate fields declare readonly: true because only the engine writes them. Consolidated totals aggregate the home field. Refused under dynamic and fixed.

Nested Shape: CurrencyConfig.homeAmount

Property Type Required Description
field string ✅ The field on the same object that stores the amount converted into the home currency: a stored currency field in dynamic mode (it displays in localization.currency, so metadata never names the home currency), declaring readonly: true — only the engine writes it. Conventionally AMOUNT_home.
rateDate string ✅ The field on the same object holding the record's document date, whose value picks the exchange rate: a date or datetime field. Required, with no default — the engine never guesses the date (not created_at).
rateField string ✅ The field on the same object that stores the exchange rate the conversion used: a number field declaring readonly: true — only the engine writes it. Required: the home amount is stored with the rate used. Conventionally AMOUNT_rate.

Field

Properties

Property Type Required Description
name string optional Machine name (snake_case)
label string optional Human readable label
type Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | 'markdown' | 'html' | 'richtext' | 'number' | 'currency' | 'percent' | 'date' | … +35 more> ✅ Field Data Type
description string optional Tooltip/Help text
format string optional Free-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.
required boolean optional (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 } optional Physical storage constraints (ADR-0113). Owns the DDL the write contract deliberately does not imply. Absent = no storage-level constraint requested.
searchable boolean optional (default: false) Is searchable
multiple boolean optional (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.
unique boolean | 'global' | 'organization' optional Unique 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.
defaultValue any optional Default 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.
maxLength integer optional Max 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.
minLength integer optional Min 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.
valueDomain Enum<'iana_time_zone' | 'iso_4217_currency' | 'iso_3166_alpha2'> optional Standard 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.
rows integer optional Height 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.
precision integer optional Total 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.
scale integer optional Decimal 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.
min number optional Minimum 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.
max number optional Maximum 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.
useGrouping boolean optional Digit-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.
accept string[] optional Permitted upload types for media fields, as MIME types or extensions (e.g. ["image/*", ".pdf"]). Offered to the file picker AND enforced on write.
maxSize integer optional Maximum 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; … }[] optional Static 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.
picklist string optional Name 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.
reference string optional Target object name (snake_case) for lookup/master_detail fields. Required for relationship types. Used by $expand to resolve foreign key IDs into full objects. Never a stored-metadata table (sys_metadata, sys_metadata_history): their rows are served only through the metadata API, so the engine never hydrates a reference into one, and os validate, os build and the object save door refuse it. 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.
referenceVia string optional Declares 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 } optional Marks 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.
mailAssociation boolean optional Inbound 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.
deleteBehavior Enum<'set_null' | 'cascade' | 'restrict'> optional (default: "set_null") What happens if referenced record is deleted
inlineEdit boolean | Enum<'grid' | 'form'> optional Edit 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.
inlineTitle string optional Title for the inline master-detail grid
inlineColumns { name: string; label?: string; type?: Enum<'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file'>; width?: number; … }[] optional Explicit 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.
inlineAmountField string optional Numeric child field summed for the inline grid total
relatedList boolean | 'primary' optional Show this child collection as a related list on the parent's detail page (read-side mirror of inlineEdit). false = suppress; true/absent = shown as a supporting list, a side card in the record's related column (the shared "Related" tab on the tabbed page); 'primary' = part of the record's main content, drawn in the record's body (the details column, after its first field section) as a full-width table (inside the Details tab on the tabbed page, with no tab of its own). Absent on a master_detail field that sets inlineEdit, the list is 'primary' by default; write true to keep it a side card. 'primary' places a list and does not order it: the parent object's relatedLists orders the body tables and the side cards (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.
relatedListTitle string optional Title for the detail-page related list
relatedListColumns string[] optional Explicit 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.
relatedListFilter any optional Declarative 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.
displayField string optional Field shown as each candidate's label in the picker/popover (defaults to the referenced object's name/title).
descriptionField string optional Secondary field shown under the label in the quick-select popover.
lookupColumns (string | { field: string; label?: string; width?: string; type?: string })[] optional Explicit columns for the record-picker table; auto-derived from the referenced object when omitted.
lookupPageSize integer optional Rows 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 }[] optional Base filters restricting which records are selectable (e.g. only active). The structured, picker-honoured lookup filter.
dependsOn (string | { field: string; param?: string })[] optional Declares 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.
allowCreate boolean optional Allow 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.
expression string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional CEL expression the field's value is computed from, e.g. Frecord.amount * 0.1. On a formula field: computed on read, no column. On any other (stored) field: computed by the engine from the row the write stores and stored, so a client-sent value never stands and a summary can roll the column up — on every insert and every update by id (the stored row merged with the patch), and on a predicate update only when the patch moves an input (one value for every matched row, else the update is refused).
returnType Enum<'number' | 'text' | 'boolean' | 'date' | 'currency'> optional Inferred 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; … } optional Roll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted.
language string optional Programming language for syntax highlighting (e.g., javascript, python, sql)
step number optional Step increment for slider (default: 1)
currencyConfig { currencyMode?: Enum<'dynamic' | 'fixed' | 'record'>; defaultCurrency?: string; currencyField?: string; homeAmount?: object } optional Which currency an amount is in: for a currency field, and for a formula field whose returnType is currency. Absent: dynamic mode.
dimensions integer optional Vector dimensionality (e.g., 1536 for OpenAI embeddings)
trackHistory boolean optional Render this field's value changes as human-readable entries on the record activity timeline (ADR-0052 §5b). Opt-in per field.
group string optional Field group name for organizing fields in forms and layouts (e.g., "contact_info", "billing", "system")
visibleWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Predicate (CEL) — field is shown only when TRUE (else hidden). e.g. Precord.type == 'invoice'
readonlyWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Predicate (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.
requiredWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Predicate (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.
dueLike boolean optional Deadline 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.
settledWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Predicate (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> }[] optional Cell 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.
widget string optional Form 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".
hidden boolean optional (default: false) Hidden from default UI
internal boolean optional Never 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.
readonly boolean optional (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.
requiredPermissions string[] optional [ADR-0066 D3] Capabilities required to read/edit this field (mask on read, deny on write; AND-gate).
maskingRule Enum<'phone' | 'id_card' | 'bank_account' | 'email' | 'name'> | { keepHead: integer; keepTail: integer } optional Partial 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.
ackPlaintextMasking boolean optional [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.
system boolean optional Auto-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.
sortable boolean optional (default: true) Whether field is sortable in list views
inlineHelpText string optional Help text displayed below the field in forms
placeholder string optional Placeholder 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).
autonumberFormat string optional (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.
externalId boolean optional (default: false) Not read: no upsert, import or seed matches on this flag. A seed dataset names its match field in its own externalId; an import names it in the mapping's upsertKey.
_lock Enum<'none' | 'no-overlay' | 'no-delete' | 'full'> optional Item-level lock — controls overlay & delete (ADR-0010).
_lockReason string optional Human-readable reason shown when a write is refused by _lock.
_lockSource Enum<'artifact' | 'package' | 'env-forced'> optional Layer that set _lock (artifact | package | env-forced).
_provenance Enum<'package' | 'org' | 'env-forced'> optional Origin of the item (package | org | env-forced).
_packageId string optional Owning package machine id.
_packageVersion string optional Owning package version.
_lockDocsUrl string optional Optional 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

Property Type Required Description
notNull boolean optional Emit 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]

Property Type Required Description
label string ✅ Display label (human-readable, any case allowed)
value string ✅ Stored value (lowercase machine identifier)
description string optional Optional secondary/help text for this option. Lookup option search matches it in addition to the label; renderers may show it as supporting text.
color string optional Color code for badges/charts
default boolean optional Is default option
visibleWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Per-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.
kind Enum<'open' | 'won' | 'lost'> optional Lifecycle category of this option: 'open' (a step on the way), 'won' (the successful end: a deal's Closed Won, a task's Done, a case's Resolved) or 'lost' (the unsuccessful end: Closed Lost, Cancelled, Unqualified). Absent reads as 'open'. Required on every option of the field an object's stageField names. Only on a single-value select / radio field.

Nested Shape: Field.referenceDeletedWhen

Property Type Required Description
field string ✅ The SIBLING select field on the same object whose value marks the target as deleted (snake_case).
value string ✅ The option value of that select field that means "the referenced record was deleted by the platform".

Nested Shape: Field.inlineColumns[number]

Property Type Required Description
name string ✅ 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.
label string optional Column header; defaults to the child field's label via hydration.
type Enum<'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file'> optional Cell 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.
width number optional Fixed column width in px; omitted columns use type-based role sizing (text flexes, numeric/date/select stay fixed).
required boolean optional Cell is flagged inline-invalid while empty. Computed columns are never required.
options { label: string; value: string }[] optional Select-cell options for type: 'select'; derived from the child field's options when the column declares no type.
prefix string optional Symbol 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.
step number optional Input step for numeric cells.
reference string optional Referenced object for type: 'lookup' cells; derived from the child lookup field when the column declares no type.
displayField string optional Label field shown for a picked lookup record.
idField string optional Id field stored for a picked lookup record.
multiple boolean optional Multi-value column: multi-record lookup, or multi-file upload cell.
accept string[] optional Accepted MIME types / extensions for a file cell's picker (e.g. ['image/*', '.pdf']); omit to accept anything.
defaultHidden boolean optional Collapsed into the grid's column chooser by default (not dropped); required columns are never default-hidden.
computed boolean optional Read-only computed column, recomputed live from sibling cells via expr and written back into the row.
expr string optional Arithmetic 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.
scale integer optional Decimal 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.
autofill boolean optional For 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.
readonlyWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Predicate (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').
requiredWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Predicate (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

Property Type Required Description
object string ✅ Source child object name for roll-up
field string optional Field on the child object to aggregate. Required for sum, min, max and avg; count counts the child rows and reads no field, so a count may omit it (ignored when given).
function Enum<'count' | 'sum' | 'min' | 'max' | 'avg'> ✅ Aggregation function to apply
relationshipField string optional FK 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.
filter any optional Predicate 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

Property Type Required Description
currencyMode Enum<'dynamic' | 'fixed' | 'record'> 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. record: each record has its own currency, the ISO 4217 code stored in the sibling field currencyField names; defaultCurrency is refused. The value is a bare number in every mode (ADR-0104 D1).
defaultCurrency string optional The currency code (ISO 4217, e.g. USD, CNY, EUR) of a fixed-mode field: its one currency, required under fixed. Not read under dynamic (the default), where amounts display in the tenant default currency, and refused under record, where each record names its own.
currencyField string optional record mode only, and required there: the name of the field on the same object that holds each record's currency — a text field declaring valueDomain: 'iso_4217_currency' (conventionally currency_code). Refused under dynamic and fixed, and never empty.
homeAmount { field: string; rateDate: string; rateField: string } optional record mode only, optional: where the engine stores this amount converted into the organization's home currency (the localization.currency setting) at write, at the rate of the record's document date, and the rate it used. field names a dynamic-mode currency field, rateDate a date / datetime field and rateField a number field, all on the same object; all three are required, and the home and rate fields declare readonly: true because only the engine writes them. Consolidated totals aggregate the home field. Refused under dynamic and fixed.

Nested Shape: Field.conditionalFormatting[number]

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

Nested Shape: Field.maskingRule

Property Type Required Description
keepHead integer ✅ Number of leading characters to leave readable
keepTail integer ✅ Number of trailing characters to leave readable

FieldMaskingKeep

Properties

Property Type Required Description
keepHead integer ✅ Number of leading characters to leave readable
keepTail integer ✅ 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

Property Type Required Description
keepHead integer ✅ Number of leading characters to leave readable
keepTail integer ✅ 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

Property Type Required Description
name string ✅ 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.
label string optional Column header; defaults to the child field's label via hydration.
type Enum<'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file'> optional Cell 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.
width number optional Fixed column width in px; omitted columns use type-based role sizing (text flexes, numeric/date/select stay fixed).
required boolean optional Cell is flagged inline-invalid while empty. Computed columns are never required.
options { label: string; value: string }[] optional Select-cell options for type: 'select'; derived from the child field's options when the column declares no type.
prefix string optional Symbol 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.
step number optional Input step for numeric cells.
reference string optional Referenced object for type: 'lookup' cells; derived from the child lookup field when the column declares no type.
displayField string optional Label field shown for a picked lookup record.
idField string optional Id field stored for a picked lookup record.
multiple boolean optional Multi-value column: multi-record lookup, or multi-file upload cell.
accept string[] optional Accepted MIME types / extensions for a file cell's picker (e.g. ['image/*', '.pdf']); omit to accept anything.
defaultHidden boolean optional Collapsed into the grid's column chooser by default (not dropped); required columns are never default-hidden.
computed boolean optional Read-only computed column, recomputed live from sibling cells via expr and written back into the row.
expr string optional Arithmetic 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.
scale integer optional Decimal 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.
autofill boolean optional For 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.
readonlyWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Predicate (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').
requiredWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Predicate (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]

Property Type Required Description
label string ✅ Option label shown in the select cell.
value string ✅ Stored option value; must match the child select field's option values.

LocationCoordinates

Properties

Property Type Required Description
latitude number ✅ Latitude coordinate
longitude number ✅ Longitude coordinate
altitude number optional Altitude in meters
accuracy number optional Accuracy in meters

SelectOption

Properties

Property Type Required Description
label string ✅ Display label (human-readable, any case allowed)
value string ✅ Stored value (lowercase machine identifier)
description string optional Optional secondary/help text for this option. Lookup option search matches it in addition to the label; renderers may show it as supporting text.
color string optional Color code for badges/charts
default boolean optional Is default option
visibleWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object } optional Per-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.
kind Enum<'open' | 'won' | 'lost'> optional Lifecycle category of this option: 'open' (a step on the way), 'won' (the successful end: a deal's Closed Won, a task's Done, a case's Resolved) or 'lost' (the unsuccessful end: Closed Lost, Cancelled, Unqualified). Absent reads as 'open'. Required on every option of the field an object's stageField names. Only on a single-value select / radio field.

UniqueScope

Union Options

This schema accepts one of the following structures:

Option 1

Type: boolean


Option 2

Type: 'global'


Option 3

Type: 'organization'