Define business entities with ObjectSchema — the core building block of every ObjectStack application

Object Metadata

An Object is the foundational metadata type in ObjectStack. It defines a business entity — its fields, capabilities, indexes, and behaviors. Each Object maps to a database table/collection and automatically gets CRUD APIs, UI forms, and query support.

Basic Structure

import { ObjectSchema, Field } from '@objectstack/spec/data';

export const Account = ObjectSchema.create({
  name: 'account',
  label: 'Account',
  pluralLabel: 'Accounts',
  icon: 'building',
  description: 'Companies and organizations',

  fields: {
    name: Field.text({ label: 'Account Name', required: true }),
    industry: Field.select({
      label: 'Industry',
      options: [
        { label: 'Technology', value: 'technology' },
        { label: 'Finance', value: 'finance' },
        { label: 'Healthcare', value: 'healthcare' },
      ],
    }),
    annual_revenue: Field.currency({ label: 'Annual Revenue', scale: 2 }),
    owner: Field.user({ label: 'Owner', required: true }),
  },

  enable: {
    apiEnabled: true,
    searchable: true,
    trackHistory: true,
  },
});

Properties

Identity

Property	Type	Required	Description
`name`	`string`	✅	Machine name (`snake_case`). Immutable after creation.
`label`	`string`	optional	Human-readable singular label (e.g. `'Account'`)
`pluralLabel`	`string`	optional	Plural label (e.g. `'Accounts'`)
`description`	`string`	optional	Developer documentation
`icon`	`string`	optional	Icon name (Lucide/Material)
`tags`	`string[]`	optional	Categorization tags (e.g. `['sales', 'system']`)

Data

Property	Type	Required	Description
`fields`	`Record<string, Field>`	✅	Field definitions. Keys must be `snake_case`.
`indexes`	`Index[]`	optional	Database performance indexes
`datasource`	`string`	optional	Target datasource ID. Default: `'default'`

Display

Property	Type	Required	Description
`nameField`	`string`	optional	The stored field used as the record display name, e.g. `'name'` or `'title'` (ADR-0079). The deprecated alias `displayNameField` is still accepted.
`titleFormat`	`string`	optional	Deprecated (ADR-0079 → `nameField`). Render-only title template (e.g. `'{{record.name}} - {{record.code}}'`); an explicit `nameField` takes precedence
`highlightFields`	`string[]`	optional	Most-important fields in priority order — default list columns, cards, previews, detail highlight strip (ADR-0085; formerly `compactLayout` — the old spelling was retired and is now rejected)
`stageField`	`string \| false`	optional	Linear lifecycle field; `false` declares the status field non-linear and suppresses stage heuristics (ADR-0085)
`recordName`	`object`	optional	Record name auto-generation config

Capabilities (`enable`)

Control which platform features are active for this object:

enable: {
  trackHistory: true,      // Field history tracking for audit
  searchable: true,        // Include in global search index
  apiEnabled: true,        // Expose via REST/GraphQL APIs
  apiMethods: ['get', 'list', 'create', 'update', 'delete'],
  files: true,             // File attachments
  feeds: true,             // Activity feed and comments
  activities: true,        // Tasks and events tracking
  trash: true,             // Soft delete with restore
  mru: true,               // Most Recently Used tracking
  clone: true,             // Deep record cloning
}

Flag	Default	Description
`trackHistory`	`false`	Field history tracking for audit compliance
`searchable`	`true`	Index records for global search
`apiEnabled`	`true`	Expose object via automatic APIs
`apiMethods`	all	Whitelist of allowed API operations
`files`	`false`	Enable file attachments
`feeds`	`false`	Enable social feed and comments
`activities`	`false`	Enable tasks and events tracking
`trash`	`true`	Enable soft delete with restore
`mru`	`true`	Track Most Recently Used list
`clone`	`true`	Allow record deep cloning

Enterprise Features

Multi-Tenancy

Row-level tenant isolation in a shared database — the tenant field is injected on write and enforced on read. Database-per-tenant isolation is an environment/deployment choice (each environment carries its own database URL), not object metadata.

tenancy: {
  enabled: true,
  tenantField: 'tenant_id',
}

Soft Delete

softDelete: {
  enabled: true,
  field: 'deleted_at',
  cascadeDelete: false,
}

Versioning

versioning: {
  enabled: true,
  strategy: 'snapshot',       // 'snapshot' | 'delta' | 'event-sourcing'
  retentionDays: 365,
  versionField: 'version',
}

Data Lifecycle (Retention & Rotation)

Declares how long the object's data lives and how its space is reclaimed (ADR-0057). The platform LifecycleService (registered by ObjectQLPlugin, default-on) sweeps declared policies hourly. Objects without a lifecycle block keep permanent record semantics — nothing is ever deleted.

// High-frequency telemetry: rotation window + age reap
lifecycle: {
  class: 'telemetry',
  retention: { maxAge: '14d' },
  storage: { strategy: 'rotation', shards: 14, unit: 'day' },
}

// Ephemeral rows: TTL on the natural expiry field
lifecycle: {
  class: 'transient',
  ttl: { field: 'expires_at', expireAfter: '1d' },
}

// Compliance ledger: hot window, then cold storage
lifecycle: {
  class: 'audit',
  retention: { maxAge: '90d' },
  archive: { after: '90d', to: 'archive', keep: '7y' },
}

// Mixed table (live workflow state + terminal history): scope the reap
lifecycle: {
  class: 'telemetry',
  retention: { maxAge: '30d', onlyWhen: { status: { $in: ['completed', 'failed'] } } },
}

Key	Description
`class`	Persistence contract (see table below); `record` is the implicit default
`retention.maxAge`	Age-based reap on `created_at`
`retention.onlyWhen`	Row filter the reap is scoped to (per-field equality or `{ $in: [...] }`); rows outside it are retained regardless of age. Incompatible with rotation `storage` and `archive`
`ttl`	Per-row expiry: `field` + `expireAfter`
`storage`	`{ strategy: 'rotation', shards, unit }` — time-shard + O(1) shard `DROP` (SQLite)
`archive`	Cold-store hand-off: `after` (must equal `retention.maxAge`) + `to` (datasource name) + optional `keep`
`reclaim`	Space reclamation after sweeps (default on for non-`record`)

Class	Contract	Typical use
`record`	Business truth — permanent, no policies allowed	accounts, invoices
`audit`	Compliance ledger — retain → archive → delete	audit logs
`telemetry`	High-frequency log — rotation / short retention	activity streams, job runs
`transient`	Ephemeral state — TTL auto-expire	receipts, device codes
`event`	Bus messages — very short TTL (hours)	scheduled fan-out

Enforcement rules:

A non-record class must declare at least one bounding policy (retention, ttl, or rotation storage) — rejected at parse time otherwise. Policies on record are rejected too.
Duration literals are <n> + h/d/w/y (e.g. '6h', '14d', '7y'); archive.after must equal retention.maxAge.
An archive-declared object is never hot-deleted before the archive copy succeeded. No datasource registered under the archive.to name ⇒ rows are retained (safe default), not dropped.
Registering a datasource named telemetry routes every telemetry/event/audit object to it — separate storage, opt-in purely by the datasource's existence.

Operations knobs live in the lifecycle settings namespace: a runtime enabled switch, tenant-scoped retention_overrides (a regulated tenant sets years while dev keeps days), row quotas and growth_alert_rows (observe-and-alert only). OS_LIFECYCLE_DISABLED=1 disables sweeping entirely.

Record Name

Auto-generate unique record identifiers:

recordName: {
  type: 'autonumber',
  displayFormat: 'ACC-{0000}',   // ACC-0001, ACC-0002, ...
  startNumber: 1,
}

Property	Type	Description
`type`	`'text' \| 'autonumber'`	Generation mode
`displayFormat`	`string`	Pattern (e.g. `'INV-{YYYY}-{0000}'`)
`startNumber`	`number`	Starting number (default: 1)

Indexes

Optimize query performance:

indexes: [
  { fields: ['name'], type: 'btree', unique: false },
  { fields: ['email'], type: 'btree', unique: true },
  { fields: ['type', 'status'], type: 'btree', unique: false },
]

Property	Type	Required	Description
`fields`	`string[]`	✅	Fields in the index
`type`	`enum`	optional	`'btree'`, `'hash'`, `'gin'`, `'gist'`, `'fulltext'` (default: `'btree'`)
`unique`	`boolean`	optional	Enforce uniqueness (default: `false`)
`partial`	`string`	optional	Conditional index (SQL WHERE clause)
`name`	`string`	optional	Index name (auto-generated if omitted)

Additional Properties

Property	Type	Description
`active`	`boolean`	Is object active (default: `true`)
`isSystem`	`boolean`	System object, protected from deletion (default: `false`)
`abstract`	`boolean`	Abstract base, cannot be instantiated (default: `false`)
`sharingModel`	`enum`	Org-Wide Default record visibility (ADR-0055/0056/0090). Canonical four only: `'private'`, `'public_read'`, `'public_read_write'`, `'controlled_by_parent'` (detail visibility derived from its master). The legacy aliases (`'read'`, `'read_write'`, `'full'`) were removed from the enum (ADR-0090 D4) — authoring rejects them. Unset on a custom object resolves to `'private'` (ADR-0090 D1)
`keyPrefix`	`string`	Short prefix for record IDs (e.g. `'001'`)
`validations`	`ValidationRule[]`	Object-level validation rules (see Validation)

Naming Conventions

Element	Convention	Example
Object `name`	`snake_case`	`project_task`, `user_profile`
Export constant	`PascalCase`	`ProjectTask`, `UserProfile`
Config keys	`camelCase`	`trackHistory`, `apiEnabled`

Complete Example

import { ObjectSchema, Field } from '@objectstack/spec/data';

export const ProjectTask = ObjectSchema.create({
  name: 'project_task',
  label: 'Project Task',
  pluralLabel: 'Project Tasks',
  icon: 'check-square',
  description: 'Tasks within a project',

  fields: {
    title: Field.text({ label: 'Title', required: true, maxLength: 255 }),
    description: Field.textarea({ label: 'Description' }),
    status: Field.select({
      label: 'Status',
      options: [
        { label: 'To Do', value: 'todo', default: true },
        { label: 'In Progress', value: 'in_progress' },
        { label: 'Done', value: 'done' },
      ],
    }),
    priority: Field.select({
      label: 'Priority',
      options: [
        { label: 'Low', value: 'low' },
        { label: 'Medium', value: 'medium', default: true },
        { label: 'High', value: 'high' },
      ],
    }),
    due_date: Field.date({ label: 'Due Date' }),
    assignee: Field.user({ label: 'Assignee' }),
    project: Field.lookup('project', { label: 'Project', required: true }),
    estimated_hours: Field.number({ label: 'Estimated Hours', min: 0 }),
  },

  indexes: [
    { fields: ['status'], type: 'btree', unique: false },
    { fields: ['project', 'status'], type: 'btree', unique: false },
  ],

  enable: {
    apiEnabled: true,
    searchable: true,
    trackHistory: true,
    feeds: true,
    trash: true,
  },

  validations: [
    {
      name: 'due_date_future',
      type: 'script',
      severity: 'warning',
      message: 'Due date should be in the future',
      condition: 'record.due_date < today()',
      events: ['insert'],
    },
  ],
});

Field Metadata — All field types and configuration options
Validation Metadata — Data integrity rules
View Metadata — Customize how objects are displayed
Permission Metadata — Control access to objects

Object Metadata

On this page