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

Data

Display

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
  clone: true,             // Deep record 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,
}

The tenant column defaults to nothing at the spec level: leave tenantField undeclared and the driver scopes by organization_id — the kernel-injected column the RLS predicates use. Declare it only when an object's tenant column genuinely is not organization_id, and only when the object really has that field (a declared name for a column that does not exist is ignored, and the organization_id fallback applies):

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

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'] } } },
}

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.

Indexes

Optimize query performance:

indexes: [
  { fields: ['name'] },
  { fields: ['email'], unique: 'organization' },
  { fields: ['type', 'status'] },
]

Additional Properties

Lifecycle bucket (managedBy)

managedBy declares which lifecycle bucket an object belongs to. It sets the default CRUD affordances the UI renders and the write policy the platform enforces. The enforced policy is the resolved affordance — the bucket default with any userActions override applied (resolveCrudAffordances) — not the bare bucket string.

engine-owned vs. system-data (ADR-0103, #3355). Both hold a platform-defined schema no tenant may model; they differ on who owns the rows:

• engine-owned — jobs, notifications, approval runtime rows, sys_record_share, sys_automation_run, the metadata store, sys_secret, audit trails — written only by their owning service under a system context, never through the generic /data API. Locked by default, and a fail-closed guard (assertEngineOwnedWriteAllowed) rejects user-context generic writes.
• system-data — the schema is the platform's, the data is the admin's or the user's: the RBAC link tables, sys_user_preference, sys_approval_delegation, the messaging config grids. New / Edit / Delete / Export by default, and no write guard covers the bucket — a writable default has nothing to fail closed on:

export const SysUserPreference = ObjectSchema.create({
  name: 'sys_user_preference',
  // New / Edit / Delete / Export by default — no `userActions` needed. RLS /
  // delegated administration is the actual authz.
  managedBy: 'system-data',
  // …
});

Pick between them on the data, not the table name: if no user ever writes a row through the generic API, it is engine-owned. Declaring system-data on an object whose resolved affordances grant no create, edit or delete is a contradiction, and ObjectSchema.create() refuses it.

userActions NARROWS system-data (an editable-only grid: { create: false, delete: false }) and OPENS a verb on append-only. Either way it is an affordance declaration; the real authorization for these rows is still enforced by RLS, delegated administration, and permission sets.

CSV import on system-data is opt-in

system-data is the one writable bucket that does not hand out the CSV bulk-import wizard. platform is now the only bucket whose default grants import:

export const SysUserPermissionSet = ObjectSchema.create({
  name: 'sys_user_permission_set',
  managedBy: 'system-data',
  // No `userActions` → New / Edit / Delete / Export, but no Import wizard.
});

export const SysHolidayCalendar = ObjectSchema.create({
  name: 'sys_holiday_calendar',
  managedBy: 'system-data',
  // Bulk loading a year of dates from a spreadsheet is the whole point here,
  // so this object asks for the wizard explicitly.
  userActions: { import: true },
});

The reason is leverage, not authorization. The bucket's charter members are the RBAC link tables — sys_user_position, sys_user_permission_set, sys_position_permission_set — which are the grant surface of the entire permission model. Every row a CSV import writes still passes the delegated-admin gate, RLS and permission-set adjudication one at a time, so an admin who cannot grant a permission set by hand cannot grant it by file either. What differs is blast radius: row by row, one misclick affects one person; one wrong CSV is a bulk grant with no natural review rhythm. Making the wizard a per-object declaration keeps "nobody thought about import" resolving to the safe answer.

Naming Conventions

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'] },
    { fields: ['project', 'status'] },
  ],

  enable: {
    apiEnabled: true,
    searchable: true,
    trackHistory: true,
    feeds: 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'],
    },
  ],
});

Related

• 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