Skip to content

object.mdx

Latest commit

 

History

History
306 lines (214 loc) · 19.5 KB

object.mdx

File metadata and controls

306 lines (214 loc) · 19.5 KB
Raw
title Object
description Object protocol schemas

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

API Operations Enum

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

TypeScript Usage

import { ApiMethod, Index, Lifecycle, LifecycleClass, Object, ObjectAccessConfig, ObjectCapabilities, ObjectExtension, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, ObjectRequiredPermissions, PerOperationRequiredPermissions, RowCrudActionOverride, TenancyConfig } from '@objectstack/spec/data';
import type { ApiMethod, Index, Lifecycle, LifecycleClass, Object, ObjectAccessConfig, ObjectCapabilities, ObjectExtension, ObjectExternalBinding, ObjectFieldGroup, ObjectOwnershipEnum, ObjectRequiredPermissions, PerOperationRequiredPermissions, RowCrudActionOverride, TenancyConfig } from '@objectstack/spec/data';

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

ApiMethod

Allowed Values

  • get
  • list
  • create
  • update
  • delete
  • upsert
  • bulk
  • aggregate
  • history
  • search
  • restore
  • purge
  • import
  • export

Index

Properties

Property Type Required Description
name string optional Index name (auto-generated if not provided)
fields string[] ✅ Fields included in the index
type Enum<'btree' | 'hash' | 'gin' | 'gist' | 'fulltext'> ✅ Index algorithm type
unique boolean ✅ Whether the index enforces uniqueness
partial string optional Partial index condition (SQL WHERE clause for conditional indexes)

Lifecycle

Properties

Property Type Required Description
class Enum<'record' | 'audit' | 'telemetry' | 'transient' | 'event'> ✅ Persistence contract: record (business truth, permanent) | audit (compliance ledger) | telemetry (high-freq log) | transient (ephemeral state) | event (bus messages).
retention { maxAge: string; onlyWhen?: Record<string, string | number | boolean | { $in: string | number[] }> } optional Age-based retention window enforced by the LifecycleService Reaper.
ttl { field: string; expireAfter: string } optional Per-row TTL auto-expiry (transient/event classes).
storage { strategy: 'rotation'; shards: integer; unit: Enum<'day' | 'week' | 'month'> } optional Physical storage strategy for high-frequency telemetry (LifecycleService Rotator).
archive { after: string; to: string; keep?: string } optional Cold-store archival (LifecycleService Archiver) — audit-class hot→cold hand-off.
reclaim boolean optional Run driver space reclamation (SQLite incremental_vacuum) after sweeping this object. Default true for non-record classes.

LifecycleClass

Allowed Values

  • record
  • audit
  • telemetry
  • transient
  • event

Object

Properties

Property Type Required Description
name string ✅ Machine unique key (snake_case). Immutable.
label string optional Human readable singular label (e.g. "Account")
pluralLabel string optional Human readable plural label (e.g. "Accounts")
description string optional Developer documentation / description
icon string optional Icon name (Lucide/Material) for UI representation
isSystem boolean optional Is system object (protected from deletion; defaults its org-wide sharing to public when no sharingModel is set — plugin-sharing)
managedBy Enum<'platform' | 'config' | 'system' | 'engine-owned' | 'append-only' | 'better-auth'> optional Lifecycle bucket — platform (user CRUD) | config (admin authored) | system (engine-managed schema, writable via userActions) | engine-owned (engine owns the lifecycle, no user writes) | append-only (audit) | better-auth (identity). UI clients honour the resolved affordance matrix.
ownership Enum<'user' | 'org' | 'none'> optional Record-ownership model: user (default — injects reassignable owner_id) | org | none (no per-record owner, skips owner_id). Distinct from the package own/extend contribution kind.
userActions { create?: boolean; import?: boolean; edit?: boolean | { enabled?: boolean; visibleWhen?: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }; disabledWhen?: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } }; delete?: boolean | { enabled?: boolean; visibleWhen?: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }; disabledWhen?: string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } }; … } optional Per-object override of the resolved CRUD affordance matrix.
systemFields 'false' | { tenant?: boolean; audit?: boolean } optional Opt out of, or selectively disable, registry-level system-field auto-injection.
datasource string optional Target Datasource ID. "default" is the primary DB.
external { remoteName?: string; remoteSchema?: string; writable?: boolean; columnMap?: Record<string, string>; … } optional Remote table binding for federated (external) objects.
fields Record<string, { name?: string; label?: string; 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'>; description?: string; … }> ✅ Field definitions map. Keys must be snake_case identifiers.
indexes { name?: string; fields: string[]; type?: Enum<'btree' | 'hash' | 'gin' | 'gist' | 'fulltext'>; unique?: boolean; … }[] optional Database performance indexes
fieldGroups { key: string; label: string; icon?: string; description?: string; … }[] optional Ordered list of field groups (array order = display order). See ObjectFieldGroupSchema.
tenancy { enabled: boolean; tenantField?: string } optional Multi-tenancy configuration for SaaS applications
access { default?: Enum<'public' | 'private'> } optional [ADR-0066 D2] Object exposure posture (public-by-default vs private secure-by-default).
requiredPermissions string[] | { read?: string[]; create?: string[]; update?: string[]; delete?: string[] } optional [ADR-0066 D3/⑤] Capabilities required to access this object (AND-gate) — string[] gates all CRUD, or a {read,create,update,delete} map gates per operation.
lifecycle { class: Enum<'record' | 'audit' | 'telemetry' | 'transient' | 'event'>; retention?: object; ttl?: object; storage?: object; … } optional Data lifecycle contract (ADR-0057): class + retention/ttl/rotation/archive policies enforced by the platform LifecycleService.
validations any[] optional Object-level validation rules
activityMilestones { field: string; value: string; summary: string; type?: string }[] optional Declarative semantic activity milestones — emit a templated timeline row when a field transitions into a value, no hook code (ADR-0052 §5b.2).
nameField string optional [ADR-0079] Canonical primary title field — the stored field used as the record display name (e.g. "name", "title").
displayNameField string optional [DEPRECATED → nameField] Field to use as the record display name (e.g., "name", "title"). Accepted as an alias for nameField.
titleFormat string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional [DEPRECATED → nameField (ADR-0079)] Render-only title template; the server cannot return or query it, and an explicit nameField now takes precedence. Migrate a single-field title to nameField, a composite to a formula field designated as nameField.
highlightFields string[] optional [ADR-0085] Ordered most-important fields; first entry wins where only one fits. Drives default columns, cards, previews, detail highlight strip. Renamed from compactLayout.
stageField string | 'false' optional [ADR-0085] Lifecycle stage field (linear/ordered), or false to declare the status field non-linear and suppress stage heuristics. Absent = heuristic detection allowed.
listViews Record<string, { name?: string; label?: string; type?: Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart' | 'tree'>; data?: { provider: 'object'; object: string } | { provider: 'api'; read?: object; write?: object } | { provider: 'value'; items: any[] } | { provider: 'schema'; schemaId: string; schema?: Record<string, any> }; … }> optional Built-in named list views (segmented tabs) shipped with the object schema — "views" mode, dropdown userFilters allowed, no page-only tabs (ADR-0047)
searchableFields string[] optional Fields the $search query matches against (ADR-0061). Canonical default for the record picker, list quick-search and global search; views may narrow it. When unset, search auto-defaults to the name/title field plus short-text fields.
enable { trackHistory?: boolean; searchable?: boolean; apiEnabled?: boolean; apiMethods?: Enum<'get' | 'list' | 'create' | 'update' | 'delete' | 'upsert' | 'bulk' | 'aggregate' | 'history' | 'search' | 'restore' | 'purge' | 'import' | 'export'>[]; … } optional Enabled system features modules
sharingModel Enum<'private' | 'public_read' | 'public_read_write' | 'controlled_by_parent'> optional Org-Wide Default record visibility (OWD) for INTERNAL users. Canonical four only (legacy aliases removed, ADR-0090 D4): private (owner-only) | public_read (everyone reads, owner writes) | public_read_write (everyone reads+writes) | controlled_by_parent (derived from the master record). A CUSTOM object that omits this resolves to private at runtime (ADR-0090 D1).
externalSharingModel Enum<'private' | 'public_read' | 'public_read_write' | 'controlled_by_parent'> optional [ADR-0090 D11] OWD for external (portal/partner) principals. Defaults to private; must be <= sharingModel in openness.
publicSharing { enabled?: boolean; allowedAudiences?: Enum<'public' | 'link_only' | 'signed_in' | 'email'>[]; allowedPermissions?: Enum<'view' | 'comment' | 'edit'>[]; maxExpiryDays?: integer; … } optional Public share-link policy (Notion/Figma-style link sharing)
actions { name: string; label: string; objectName?: string; icon?: string; … }[] optional Actions associated with this object (auto-populated from top-level actions via objectName)
protection { lock: Enum<'none' | 'no-overlay' | 'no-delete' | 'full'>; reason: string; docsUrl?: string } optional Package author protection block — lock policy for this object.
_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.

ObjectAccessConfig

Properties

Property Type Required Description
default Enum<'public' | 'private'> ✅ Default exposure posture: public (covered by wildcard grants) | private (needs explicit grant; exempt from wildcard RLS).

ObjectCapabilities

Properties

Property Type Required Description
trackHistory boolean ✅ Show the record History tab (audit-trail UI). Pair with per-field trackHistory to pick which field diffs are summarized; audit capture itself is always on for compliance
searchable boolean ✅ Index records for global search
apiEnabled boolean ✅ Expose object via automatic APIs
apiMethods Enum<'get' | 'list' | 'create' | 'update' | 'delete' | 'upsert' | 'bulk' | 'aggregate' | 'history' | 'search' | 'restore' | 'purge' | 'import' | 'export'>[] optional Whitelist of allowed API operations
files boolean ✅ Generic record Attachments panel (sys_attachment). Opt-in: true surfaces the panel and permits attachments targeting this object; otherwise creation is rejected. Field.file/Field.image are independent
feeds boolean ✅ Record comments/collaboration feed. Default on; explicit false hides the feed UI and rejects new comments for this object
activities boolean ✅ Record activity timeline (sys_activity mirror of CRUD). Default on; explicit false stops mirroring and hides the timeline
trash boolean ✅ Enable soft-delete with restore capability
mru boolean ✅ Track Most Recently Used (MRU) list for users
clone boolean ✅ Allow record deep cloning

ObjectExtension

Properties

Property Type Required Description
extend string ✅ Target object name (FQN) to extend
fields Record<string, { name?: string; label?: string; 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'>; description?: string; … }> optional Fields to add/override
label string optional Override label for the extended object
pluralLabel string optional Override plural label for the extended object
description string optional Override description for the extended object
validations any[] optional Additional validation rules to merge into the target object
indexes { name?: string; fields: string[]; type?: Enum<'btree' | 'hash' | 'gin' | 'gist' | 'fulltext'>; unique?: boolean; … }[] optional Additional indexes to merge into the target object
priority integer optional Merge priority (higher = applied later)

ObjectExternalBinding

External datasource binding (ADR-0015)

Properties

Property Type Required Description
remoteName string optional Remote table/view name. Defaults to object.name.
remoteSchema string optional Remote schema/database qualifier.
writable boolean ✅ Per-object write opt-in (also requires datasource.external.allowWrites).
columnMap Record<string, string> optional Remote column name → local field name.
introspectedAt string optional Set by os datasource introspect; informational.
ignoreColumns string[] optional Remote columns to skip during validation (dev convenience).

ObjectFieldGroup

Properties

Property Type Required Description
key string ✅ Group machine key (snake_case). Referenced by Field.group.
label string ✅ Group display label
icon string optional Icon name (Lucide/Material) for the group header
description string optional Optional description shown under the group header
collapse Enum<'none' | 'expanded' | 'collapsed'> ✅ [ADR-0085] Section collapse behaviour: 'none' (always open, no toggle), 'expanded' (collapsible, starts open), 'collapsed' (collapsible, starts closed).
defaultExpanded boolean optional [DEPRECATED → collapse] true → 'expanded', false → 'collapsed'.
collapsible boolean optional [DEPRECATED → collapse] Boolean pair with collapsed; use the collapse enum.
collapsed boolean optional [DEPRECATED → collapse] Boolean pair with collapsible; use the collapse enum.

ObjectOwnershipEnum

Allowed Values

  • own
  • extend

ObjectRequiredPermissions

Union Options

This schema accepts one of the following structures:

Option 1

Type: string[]

Option 2

Properties

Property Type Required Description
read string[] optional Capabilities required to read (find/findOne/count/aggregate).
create string[] optional Capabilities required to create (insert).
update string[] optional Capabilities required to update (update/transfer/restore).
delete string[] optional Capabilities required to delete (delete/purge).

PerOperationRequiredPermissions

Properties

Property Type Required Description
read string[] optional Capabilities required to read (find/findOne/count/aggregate).
create string[] optional Capabilities required to create (insert).
update string[] optional Capabilities required to update (update/transfer/restore).
delete string[] optional Capabilities required to delete (delete/purge).

RowCrudActionOverride

Boolean-or-predicates override for a built-in row CRUD affordance.

Properties

Property Type Required Description
enabled boolean optional Object-level on/off for the generic affordance; same meaning as the bare boolean form. Omitted → managedBy bucket default.
visibleWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Per-record CEL predicate; false → hide the row button for that record. Fail-closed.
disabledWhen string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object } optional Per-record CEL predicate; true → render the row button disabled for that record. Fail-soft.

TenancyConfig

Properties

Property Type Required Description
enabled boolean ✅ Enable multi-tenancy for this object
tenantField string ✅ Field name for tenant identifier