title	Object Metadata
description	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'`)
`ownership`	`enum`	Record-ownership model: `'user'` (default — injects the reassignable `owner_id` lookup, engaging owner-scoped RLS, "My" views and owner reports), `'org'`, or `'none'` (no per-record owner — Dataverse-style catalog / junction tables, skips `owner_id`). Distinct from the package `own`/`extend` contribution kind.
`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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Object Metadata

Basic Structure

Properties

Identity

Data

Display

Capabilities (`enable`)

Enterprise Features

Multi-Tenancy

Soft Delete

Versioning

Data Lifecycle (Retention & Rotation)

Record Name

Indexes

Additional Properties

Naming Conventions

Complete Example

Related

Uh oh!

FilesExpand file tree

objects.mdx

Latest commit

History

objects.mdx

File metadata and controls

Object Metadata

Basic Structure

Properties

Identity

Data

Display

Capabilities (enable)

Enterprise Features

Multi-Tenancy

Soft Delete

Versioning

Data Lifecycle (Retention & Rotation)

Record Name

Indexes

Additional Properties

Naming Conventions

Complete Example

Related

Capabilities (`enable`)