ObjectStackObjectStack

Field

Field protocol schemas

Field Type Enum

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

TypeScript Usage

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

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

Address

Properties

PropertyTypeRequiredDescription
streetstringoptionalStreet address
citystringoptionalCity name
statestringoptionalState/Province
postalCodestringoptionalPostal/ZIP code
countrystringoptionalCountry name or code
countryCodestringoptionalISO country code (e.g., US, GB)
formattedstringoptionalFormatted address string

ComputedFieldCache

Properties

PropertyTypeRequiredDescription
enabledboolean✅Enable caching for computed field results
ttlnumber✅Cache TTL in seconds (0 = no expiration)
invalidateOnstring[]✅Field paths that invalidate cache (e.g., ["inventory.quantity", "pricing.base_price"])

CurrencyConfig

Properties

PropertyTypeRequiredDescription
precisioninteger✅Decimal precision (default: 2)
currencyModeEnum<'dynamic' | 'fixed'>✅Currency mode: dynamic (user selectable) or fixed (single currency)
defaultCurrencystring✅Default or fixed currency code (ISO 4217, e.g., USD, CNY, EUR)

CurrencyValue

Properties

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

DataQualityRules

Properties

PropertyTypeRequiredDescription
uniquenessboolean✅Enforce unique values across all records
completenessnumber✅Minimum ratio of non-null values (0-1, default: 0 = no requirement)
accuracyObjectoptionalAccuracy validation configuration

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' | '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
descriptionstringoptionalTooltip/Help text
formatstringoptionalFormat string (e.g. email, phone)
columnNamestringoptionalPhysical column name in the target datasource. Defaults to the field key when not set.
requiredbooleanoptionalIs required
searchablebooleanoptionalIs searchable
multiplebooleanoptionalAllow multiple values (Stores as Array/JSON). Applicable for select, lookup, file, image.
uniquebooleanoptionalIs unique constraint
defaultValueanyoptionalDefault value
maxLengthnumberoptionalMax character length
minLengthnumberoptionalMin character length
precisionnumberoptionalTotal digits
scalenumberoptionalDecimal places
minnumberoptionalMinimum value
maxnumberoptionalMaximum value
optionsObject[]optionalStatic options for select/multiselect
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.
referenceFiltersstring[]optionalFilters applied to lookup dialogs (e.g. "active = true")
deleteBehaviorEnum<'set_null' | 'cascade' | 'restrict'>optionalWhat 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
inlineColumnsany[]optionalExplicit columns for the inline grid (derived from the child object when omitted)
inlineAmountFieldstringoptionalNumeric child field summed for the inline grid total
relatedListboolean | stringoptionalShow 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).
relatedListTitlestringoptionalTitle for the detail-page related list
relatedListColumnsany[]optionalExplicit columns for the detail-page related list (derived from the child object when omitted)
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.
lookupColumnsstring | Object[]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).
lookupFiltersObject[]optionalBase filters restricting which records are selectable (e.g. only active). Structured, picker-honoured form of referenceFilters.
dependsOnstring | Object[]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 | ObjectoptionalFormula expression (CEL). e.g. Frecord.amount * 0.1
returnTypeEnum<'number' | 'text' | 'boolean' | 'date'>optionalInferred value type of a formula field (number/text/boolean/date)
summaryOperationsObjectoptionalRoll-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)
currencyConfigObjectoptionalConfiguration for currency field type
dimensionsintegeroptionalVector dimensionality (e.g., 1536 for OpenAI embeddings)
vectorConfigObjectoptionalConfiguration for vector field type (AI/ML embeddings)
fileAttachmentConfigObjectoptionalConfiguration for file and attachment field types
trackHistorybooleanoptionalRender this field's value changes as human-readable entries on the record activity timeline (ADR-0052 §5b). Opt-in per field.
dependenciesstring[]optionalArray of field names that this field depends on (for formulas, visibility rules, etc.)
groupstringoptionalField group name for organizing fields in forms and layouts (e.g., "contact_info", "billing", "system")
visibleWhenstring | ObjectoptionalPredicate (CEL) — field is shown only when TRUE (else hidden). e.g. Precord.type == 'invoice'
readonlyWhenstring | ObjectoptionalPredicate (CEL) — field is read-only when TRUE. e.g. Precord.status == 'paid'
requiredWhenstring | ObjectoptionalPredicate (CEL) — field is required when TRUE. Canonical name for conditionalRequired.
conditionalRequiredstring | ObjectoptionalPredicate (CEL) — field is required when TRUE. Alias of requiredWhen.
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".
hiddenbooleanoptionalHidden from default UI
readonlybooleanoptionalRead-only — never editable in forms, AND server-enforced on UPDATE: a non-system write to this field is silently dropped from the payload (#2948/#3003; symmetric with readonlyWhen). INSERT may still seed it (defaultValue, import).
requiredPermissionsstring[]optional[ADR-0066 D3] Capabilities required to read/edit this field (mask on read, deny on write; AND-gate).
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.
sortablebooleanoptionalWhether field is sortable in list views
inlineHelpTextstringoptionalHelp text displayed below the field in forms
autonumberFormatstringoptionalAuto-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).
indexbooleanoptionalCreate standard database index
externalIdbooleanoptionalIs 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

FileAttachmentConfig

Properties

PropertyTypeRequiredDescription
minSizenumberoptionalMinimum file size in bytes
maxSizenumberoptionalMaximum file size in bytes (e.g., 10485760 = 10MB)
allowedTypesstring[]optionalAllowed file extensions (e.g., [".pdf", ".docx", ".jpg"])
blockedTypesstring[]optionalBlocked file extensions (e.g., [".exe", ".bat", ".sh"])
allowedMimeTypesstring[]optionalAllowed MIME types (e.g., ["image/jpeg", "application/pdf"])
blockedMimeTypesstring[]optionalBlocked MIME types
virusScanboolean✅Enable virus scanning for uploaded files
virusScanProviderEnum<'clamav' | 'virustotal' | 'metadefender' | 'custom'>optionalVirus scanning service provider
virusScanOnUploadboolean✅Scan files immediately on upload
quarantineOnThreatboolean✅Quarantine files if threat detected
storageProviderstringoptionalObject storage provider name (references ObjectStorageConfig)
storageBucketstringoptionalTarget bucket name
storagePrefixstringoptionalStorage path prefix (e.g., "uploads/documents/")
imageValidationObjectoptionalImage-specific validation rules
allowMultipleboolean✅Allow multiple file uploads (overrides field.multiple)
allowReplaceboolean✅Allow replacing existing files
allowDeleteboolean✅Allow deleting uploaded files
requireUploadboolean✅Require at least one file when field is required
extractMetadataboolean✅Extract file metadata (name, size, type, etc.)
extractTextboolean✅Extract text content from documents (OCR/parsing)
versioningEnabledboolean✅Keep previous versions of replaced files
maxVersionsnumberoptionalMaximum number of versions to retain
publicReadboolean✅Allow public read access to uploaded files
presignedUrlExpirynumber✅Presigned URL expiration in seconds (default: 1 hour)

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)
colorstringoptionalColor code for badges/charts
defaultbooleanoptionalIs default option
visibleWhenstring | ObjectoptionalPer-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

VectorConfig

Properties

PropertyTypeRequiredDescription
dimensionsinteger✅Vector dimensionality (e.g., 1536 for OpenAI embeddings)
distanceMetricEnum<'cosine' | 'euclidean' | 'dotProduct' | 'manhattan'>✅Distance/similarity metric for vector search
normalizedboolean✅Whether vectors are normalized (unit length)
indexedboolean✅Whether to create a vector index for fast similarity search
indexTypeEnum<'hnsw' | 'ivfflat' | 'flat'>optionalVector index algorithm (HNSW for high accuracy, IVFFlat for large datasets)

On this page

TypeScript UsageAddressPropertiesComputedFieldCachePropertiesCurrencyConfigPropertiesCurrencyValuePropertiesDataQualityRulesPropertiesFieldPropertiesFieldTypeAllowed ValuesFileAttachmentConfigPropertiesLocationCoordinatesPropertiesSelectOptionPropertiesVectorConfigProperties