Skip to content

field.mdx

Latest commit

 

History

History
244 lines (191 loc) · 13.4 KB

field.mdx

File metadata and controls

244 lines (191 loc) · 13.4 KB
Raw
title Field
description Field protocol schemas

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

Field Type Enum

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

TypeScript Usage

import { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, Field, FieldType, LocationCoordinates, SelectOption } from '@objectstack/spec/data';
import type { Address, ComputedFieldCache, CurrencyConfig, CurrencyValue, DataQualityRules, Field, FieldType, LocationCoordinates, SelectOption } from '@objectstack/spec/data';

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

Address

Properties

Property Type Required Description
street string optional Street address
city string optional City name
state string optional State/Province
postalCode string optional Postal/ZIP code
country string optional Country name or code
countryCode string optional ISO country code (e.g., US, GB)
formatted string optional Formatted address string

ComputedFieldCache

Properties

Property Type Required Description
enabled boolean ✅ Enable caching for computed field results
ttl number ✅ Cache TTL in seconds (0 = no expiration)
invalidateOn string[] ✅ Field paths that invalidate cache (e.g., ["inventory.quantity", "pricing.base_price"])

CurrencyConfig

Properties

Property Type Required Description
precision integer ✅ Decimal precision (default: 2)
currencyMode Enum<'dynamic' | 'fixed'> ✅ Currency mode: dynamic (user selectable) or fixed (single currency)
defaultCurrency string ✅ Default or fixed currency code (ISO 4217, e.g., USD, CNY, EUR)

CurrencyValue

Properties

Property Type Required Description
value number ✅ Monetary amount
currency string ✅ Currency code (ISO 4217)

DataQualityRules

Properties

Property Type Required Description
uniqueness boolean ✅ Enforce unique values across all records
completeness number ✅ Minimum ratio of non-null values (0-1, default: 0 = no requirement)
accuracy { source: string; threshold: number } optional Accuracy validation configuration

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' | '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'> ✅ Field Data Type
description string optional Tooltip/Help text
format string optional Format string (e.g. email, phone)
required boolean optional Is required
searchable boolean optional Is searchable
multiple boolean optional Allow multiple values (Stores as Array/JSON). Applicable for select, lookup, file, image.
unique boolean optional Is unique constraint
defaultValue any optional Default value
maxLength number optional Max character length
minLength number optional Min character length
precision number optional Total digits
scale number optional Decimal places
min number optional Minimum value
max number optional Maximum value
options { label: string; value: string; color?: string; default?: boolean; … }[] optional Static options for select/multiselect
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.
deleteBehavior Enum<'set_null' | 'cascade' | 'restrict'> optional 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 any[] optional Explicit columns for the inline grid (derived from the child object when omitted)
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 (stacked under the shared "Related" tab); 'primary' = core relationship, promoted to its own tab. Prominence intent, not a layout switch (ADR-0085).
relatedListTitle string optional Title for the detail-page related list
relatedListColumns any[] optional Explicit columns for the detail-page related list (derived from the child object when omitted)
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' | 'js' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Formula expression (CEL). e.g. Frecord.amount * 0.1
returnType Enum<'number' | 'text' | 'boolean' | 'date'> optional Inferred value type of a formula field (number/text/boolean/date)
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 { precision?: integer; currencyMode?: Enum<'dynamic' | 'fixed'>; defaultCurrency?: string } optional Configuration for currency field type
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' | 'js' | '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' | 'js' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Predicate (CEL) — field is read-only when TRUE. e.g. Precord.status == 'paid'
requiredWhen string | { dialect: Enum<'cel' | 'js' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Predicate (CEL) — field is required when TRUE. Canonical name for conditionalRequired.
conditionalRequired string | { dialect: Enum<'cel' | 'js' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Predicate (CEL) — field is required when TRUE. Alias of requiredWhen.
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 Hidden from default UI
readonly boolean optional 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 (#2948/#3003) and on INSERT (#3043; 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; system-context writes (import, seed replay, migration) are exempt.
requiredPermissions string[] optional [ADR-0066 D3] Capabilities required to read/edit this field (mask on read, deny on write; AND-gate).
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 Whether field is sortable in list views
inlineHelpText string optional Help text displayed below the field in forms
autonumberFormat string optional 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).
externalId boolean optional Is external ID for upsert operations

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

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)
color string optional Color code for badges/charts
default boolean optional Is default option
visibleWhen string | { dialect: Enum<'cel' | 'js' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Per-option visibility predicate (CEL) — option is offered only when TRUE (else omitted). Same env as field visibleWhen (record + current_user). e.g. Precord.country == 'cn' or P'admin' in current_user.positions