Migration

Migration protocol — the two kinds of migration, kept apart on purpose.

A schema migration (ChangeSet + its atomic operations) reshapes the physical database to match metadata: add a field, change a type, create an object, run SQL. It is derivable from the metadata and applied by os migrate plan / os migrate apply.

A data migration rewrites the rows themselves, and whether it is done is a property of ONE DEPLOYMENT's database rather than of the installed code version — so it cannot be expressed as a ChangeSet, and its completion cannot be inferred from a release. DataMigrationFlag is the per-deployment record that one ran here and its self-check passed; consumers that would act irreversibly on migrated data gate on the flag instead of the version.

Source: packages/spec/src/system/migration.zod.ts

TypeScript Usage

import { AddFieldOperation, ChangeSetSchema, CreateObjectOperation, DataMigrationFlagSchema, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependencySchema, MigrationJournalEventSchema, MigrationOperationSchema, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system';
import type { ChangeSet, DataMigrationFlag, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, MigrationJournalEvent, MigrationOperation, ModifyFieldOperation, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system';

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

AddFieldOperation

Add a new field to an existing object

Property	Type	Required	Description
type	`'add_field'`	✅
objectName	`string`	✅	Target object name
fieldName	`string`	✅	Name of the field to add
field	`{ name?: string; label?: string; type: Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| …>; description?: string; … }`	✅	Full field definition to add

Property	Type	Required	Description
name	`string`	optional	Machine name (snake_case)
label	`string`	optional	Human readable label
type	`Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| …>`	✅	Field Data Type
description	`string`	optional	Tooltip/Help text
format	`string`	optional	Format string (e.g. email, phone)
required	`boolean`	optional (default: `false`)	Write-time contract (ADR-0113): an insert must provide a non-null value, and an update may not null it out. On a multi-value lookup (`multiple: true`) required means NON-EMPTY array — an emptied required set fails validation loudly; `[]` does not satisfy it (maintainer ruling 2026-08-18). NOT a column constraint — the physical NOT NULL is a separate explicit opt-in (`storage.notNull`), so tightening this on a deployed object is safe: existing null rows stay readable, and editable as long as the write does not touch this field.
storage	`{ notNull?: boolean }`	optional	Physical storage constraints (ADR-0113). Owns the DDL the write contract deliberately does not imply. Absent = no storage-level constraint requested.
searchable	`boolean`	optional (default: `false`)	Is searchable
multiple	`boolean`	optional (default: `false`)	Allow multiple values (Stores as Array/JSON). Applicable for select, lookup, file, image. An emptied multi-value lookup reads back as `[]`, never `null` — the rule binds every writer (cascade repair, form clears, API writes), not just cascade repair (maintainer ruling 2026-08-18).
unique	`boolean \| 'global' \| 'organization'`	optional (default: `false`)	Unique constraint and its scope (ADR-0120). 'organization' = one holder per organization (NULL-safe composite with the organization key part on organization-scoped objects) — prefer this explicit spelling in new code; true = same per-organization scope (positional synonym, stays valid); 'global' = one holder across the whole installation. 'tenant'/'org' are rejected — the word is 'organization'
defaultValue	`any`	optional	Default applied on INSERT when the field is omitted or null (`''` is a real value, not absence). Three legal shapes, discriminated in the engine's own order: a CEL Expression envelope `{ dialect: 'cel', source: 'today()' }` (accepted structurally; result type is a runtime concern); a runtime TOKEN — `NOW()` on `datetime`/`date`/`time` only, `current_user` on `user` or `lookup` with `reference: 'sys_user'` only, neither on a multi-value field; or a LITERAL, which must satisfy this field's own stored value contract (ADR-0104 D1 `valueSchemaFor`). Anything else is refused at parse time with a prescriptive message.
maxLength	`integer`	optional	Max character length (positive integer). Only authorable on types that store a bounded string: text, textarea, email, url, phone, password, markdown, html, richtext, code, signature, qrcode.
minLength	`integer`	optional	Min character length (positive integer; `minLength: 0` is refused — express "no minimum" by omitting the key). Only authorable on types that store a bounded string: text, textarea, email, url, phone, password, markdown, html, richtext, code, signature, qrcode.
precision	`integer`	optional	Total digits (non-negative integer)
scale	`integer`	optional	Decimal places (non-negative integer)
min	`number`	optional	Minimum value
max	`number`	optional	Maximum value
useGrouping	`boolean`	optional	Digit-grouping presentation hint for `number` fields — maps to `Intl.NumberFormat`'s `useGrouping`. Absent = renderer decides (interim heuristic today, locale default eventually); `false` = author opts out of grouping (e.g. a year or other ordinal/identifier integer); `true` = author pins grouping on.
accept	`string[]`	optional	Permitted upload types for media fields, as MIME types or extensions (e.g. ["image/*", ".pdf"]). Offered to the file picker AND enforced on write.
maxSize	`integer`	optional	Maximum permitted file size in BYTES for media fields. Enforced on write against the stored file size, not just checked in the browser.
options	`{ label: string; value: string; color?: string; default?: boolean; … }[]`	optional	Static options for select/multiselect
reference	`string`	optional	Target object name (snake_case) for lookup/master_detail fields. Required for relationship types. Used by $expand to resolve foreign key IDs into full objects.
referenceVia	`string`	optional	Declares this text field as the id half of a polymorphic pointer pair (ADR-0052 §5 ActivityPointer): the value is a record id of the object named by the SIBLING FIELD this key names — e.g. `record_id` with `referenceVia: 'object_name'`. The sibling must be a declared field on the same object holding an object machine name. Text fields only; mutually exclusive with `reference` (a static and a per-record target contradict). Enforced today at seed load: the value resolves as a natural key against the object the sibling column names, and an unresolvable pointer is refused loudly instead of stored verbatim. Adds no referential integrity or $expand behavior.
deleteBehavior	`Enum<'set_null' \| 'cascade' \| 'restrict'>`	optional (default: `"set_null"`)	What happens if referenced record is deleted
inlineEdit	`boolean \| Enum<'grid' \| 'form'>`	optional	Edit 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.
inlineTitle	`string`	optional	Title for the inline master-detail grid
inlineColumns	`{ name: string; label?: string; type?: Enum<'text' \| 'number' \| 'currency' \| 'date' \| 'datetime' \| 'time' \| 'select' \| 'lookup' \| 'file'>; width?: number; … }[]`	optional	Explicit columns for the inline grid (derived from the child object when omitted). Each entry is a strict, name-keyed column (`{ name, label?, type?, … }` — objectui GridColumn); identity-only entries (`{ name }`) hydrate everything else from the child object's fields. Unknown keys and the retired `field` spelling are refused at parse.
inlineAmountField	`string`	optional	Numeric child field summed for the inline grid total
relatedList	`boolean \| 'primary'`	optional	Show 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). A derived related list (relatedList: 'primary') inherits its row order from the child object's DEFAULT list view sort — the isDefault view, or the first declared list item when none is marked default; wire spelling is sort=`<field>` / sort=-`<field>`, never $orderby. A child object with no list-view sort emits no ordering parameter, and rows fall back to record-id order.
relatedListTitle	`string`	optional	Title for the detail-page related list
relatedListColumns	`string[]`	optional	Explicit columns for the detail-page related list, as child field names (e.g. ['name', 'status']); derived from the child object (highlightFields → field walk) when omitted. Strings only — labels, cell types and formatting always derive from the child object's field definitions; column objects are refused at parse.
relatedListFilter	`any`	optional	Declarative default filter for the detail-page related list: AND-composed with the parent-relationship condition `{ [referenceField]: parentId }` — an authored constraint, never a user-editable suggestion. The related-list tab badge count honors the same composed filter, so counts match the visible rows. Canonical Query-DSL FilterCondition (the same dialect as a query `where`), e.g. `{ status: { $ne: 'deleted' } }` to hide soft-deleted children.
displayField	`string`	optional	Field shown as each candidate's label in the picker/popover (defaults to the referenced object's name/title).
descriptionField	`string`	optional	Secondary field shown under the label in the quick-select popover.
lookupColumns	`(string \| { field: string; label?: string; width?: string; type?: string })[]`	optional	Explicit columns for the record-picker table; auto-derived from the referenced object when omitted.
lookupPageSize	`integer`	optional	Rows per page in the record-picker dialog (default 10).
lookupFilters	`{ field: string; operator: Enum<'eq' \| 'ne' \| 'gt' \| 'lt' \| 'gte' \| 'lte' \| 'contains' \| 'in' \| 'notIn'>; value: any }[]`	optional	Base filters restricting which records are selectable (e.g. only active). The structured, picker-honoured lookup filter.
dependsOn	`(string \| { field: string; param?: string })[]`	optional	Declares 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.
allowCreate	`boolean`	optional	Allow 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.
expression	`string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }`	optional	Formula expression (CEL). e.g. F`record.amount * 0.1`

Property	Type	Required	Description
id	`string`	✅	Unique identifier for this change set
name	`string`	✅	Human readable name for the migration
description	`string`	optional	Detailed description of what this migration does
author	`string`	optional	Author who created this migration
createdAt	`string`	optional	ISO 8601 timestamp when the migration was created
dependencies	`{ migrationId: string; package?: string }[]`	optional	Migrations that must run before this one
operations	`({ type: 'add_field'; objectName: string; fieldName: string; field: object } \| { type: 'modify_field'; objectName: string; fieldName: string; changes: Record<string, any> } \| { type: 'remove_field'; objectName: string; fieldName: string } \| { type: 'create_object'; object: object } \| … +3 more)[]`	✅	Ordered list of atomic migration operations
rollback	`({ type: 'add_field'; objectName: string; fieldName: string; field: object } \| { type: 'modify_field'; objectName: string; fieldName: string; changes: Record<string, any> } \| { type: 'remove_field'; objectName: string; fieldName: string } \| { type: 'create_object'; object: object } \| … +3 more)[]`	optional	Operations to reverse this migration

Property	Type	Required	Description
migrationId	`string`	✅	ID of the migration this depends on
package	`string`	optional	Package that owns the dependency migration

Migration

On this page