ObjectStackObjectStack

Migration schema — System Protocol reference

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

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, OrganizationOwnershipBirthMarkerSchema, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system';
import type { ChangeSet, DataMigrationFlag, DeleteObjectOperation, ExecuteSqlOperation, MigrationDependency, MigrationJournalEvent, MigrationOperation, ModifyFieldOperation, OrganizationOwnershipBirthMarker, RemoveFieldOperation, RenameObjectOperation } from '@objectstack/spec/system';

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

AddFieldOperation

Add a new field to an existing object

Properties

PropertyTypeRequiredDescription
type'add_field'✅
objectNamestring✅Target object name
fieldNamestring✅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

Nested Shape: AddFieldOperation.field

PropertyTypeRequiredDescription
namestringoptionalMachine name (snake_case)
labelstringoptionalHuman readable label
typeEnum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | …>✅Field Data Type
descriptionstringoptionalTooltip/Help text
formatstringoptionalFree-form string whose meaning depends on the field type and on the reader. The spec declares NO vocabulary for it and checks nothing but that it is a string, so any string parses on any field type. On an autonumber field it is the record-number PATTERN — the shorthand that predates autonumberFormat, which wins when both are present: format: 'INV-{0000}' mints INV-0001 on both the query engine and the SQL driver, while a value carrying no {...} token is emitted as literal text with the bare counter appended (format: 'email' mints email1). Prefer autonumberFormat on a new field. On any other field type the server does not act on it: it picks no column type, coerces no value and runs no check from it. The Studio UI reads it as a display hint, in words and with defaults that its renderers own and declare. For example, the date and datetime cells read it as a display STYLE, and on a plain-text field the shared cell-renderer resolver reads a small set of words that promote the cell to a richer renderer, such as a link; each of those falls back silently to a default rendering when it does not recognise the word. To constrain a VALUE, use the field type (the write-time record validator's built-in email, url and phone checks key on type, never on this key) or a format validation rule, whose own format key is the closed set email | url | phone | json.
requiredbooleanoptional (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. 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 }optionalPhysical storage constraints (ADR-0113). Owns the DDL the write contract deliberately does not imply. Absent = no storage-level constraint requested.
searchablebooleanoptional (default: false)Search this field when its object declares no searchableFields. The set search scans, and the set a $searchFields override may name, is then the type-based default (the text-like and select columns) plus every field marked searchable: true, of any type except secret, password and vector, which stay excluded (a virtual formula field has no stored column, so it is never scanned either). false, the default, does not remove a field the type-based default already scans; to choose the set, declare searchableFields. When the object declares searchableFields, that list is the whole search set and this flag is not read (ADR-0061).
multiplebooleanoptional (default: false)Allow multiple values (Stores as Array/JSON). Declarable ONLY on the multi-capable types — select, lookup, user, file, image — and redundantly on the inherently-multi option types (multiselect, checkboxes, tags); multiple: true on any other type, radio included, is REFUSED at parse. A cleared optional multi-value field is stored as null, the same as one never set: an empty list [] or an empty string written to it stores null, and the rule binds every writer (cascade repair, form clears, API writes). Read null and [] alike as empty, as the is_empty filter ($empty) does, since a row stored before this rule can still hold []. On a required multi-value field the empty list is refused: required means a non-empty list.
uniqueboolean | 'global' | 'organization'optionalUnique 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'. Omitted ⇒ false, EXCEPT on an autonumber field, where omitted ⇒ 'organization' (an auto-number is a business identifier, so the platform makes it unique per organization by default — the same tenant-composite shape an explicit unique: true produces). To opt an autonumber field out, write unique: false explicitly — legitimate only for a display-only sequence that is not used to identify the record; the platform's duplicate scan (os migrate duplicates) still treats every autonumber field as an identifier.
defaultValueanyoptionalDefault 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.
maxLengthintegeroptionalMax 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. Checked on the WRITTEN value only (the min/max transition-gate class): a stored value longer than a bound declared later is never re-read and survives unrelated edits — only a write carrying an over-long value is refused.
minLengthintegeroptionalMin 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. Checked on the WRITTEN value only (the min/max transition-gate class): a stored value shorter than a bound declared later is never re-read and survives unrelated edits — only a write carrying a too-short value is refused.
valueDomainEnum<'iana_time_zone' | 'iso_4217_currency' | 'iso_3166_alpha2'>optionalStandard value domain the WRITTEN value must be a member of: iana_time_zone (an IANA/tzdb zone identifier such as UTC, Asia/Kolkata, Europe/Kyiv — membership is the Intl.DateTimeFormat probe, never the Intl.supportedValuesOf enumeration, which omits UTC), iso_4217_currency (an ISO 4217 alphabetic currency code, uppercase, e.g. CHF) or iso_3166_alpha2 (an ISO 3166-1 alpha-2 country code, uppercase, e.g. CH). The same closed vocabulary and the same membership predicate as a settings specifier's valueDomain. Only authorable on text — the one type whose stored value is a single plain string naming the member. Checked on the WRITTEN value only (the min/max/maxLength transition-gate class): a stored value outside a domain declared later is never re-read and survives unrelated edits — only a write carrying a non-member is refused, with the field error code value_domain. Reach for it precisely where a pattern cannot help: ^[A-Z]{2}$ admits ZZ, and Mars/Olympus is a shape-valid zone that does not exist.
rowsintegeroptionalHeight of the INLINE multiline editor, in text rows (positive integer — the HTML textarea rows attribute; fullscreen/dialog editor surfaces size themselves and ignore it). Only authorable on multiline editor types: textarea, markdown, html, richtext. Omit it for the widget default height.
precisionintegeroptionalTotal digits (non-negative integer) — the p of a DECIMAL(p, s): the digits of the value, integer and fraction together, counted at the field's decimal places, so precision: 5, scale: 2 holds up to 999.99 and refuses 1234.5 (1234.50 is 6 digits). Enforced on writes of number, currency, percent, rating and slider fields: a value that needs more digits is refused with field code max_precision, never rounded. Counted on the STORED value: at the declared scale when one applies, else at the value's own decimal places (leading zeros never count) — so on a currency field, where scale is refused, an amount's written decimals count toward the total; a fraction-stored percent is counted two places further right (scale + 2, or 2 with no scale), which makes the count that of the percentage-point value as displayed. Not decimal places (that is scale; a currency's are its CLDR fraction digits) and not a column size: every numeric column keeps the platform's fixed exact decimal whatever this declares. Not read on any other field type.
scaleintegeroptionalDecimal places (integer 0-100). Applies to number, percent, rating and slider fields, where it is enforced on writes, and to a formula field, whose computed result is rounded to it. REFUSED on a currency field — delete it there: a currency amount's decimal places are its currency's, so the currency's CLDR fraction digits decide how the amount displays, and a currency write's decimal places stay unconstrained. OMITTED on a percent field ⇒ 0 decimal places, so a stored 0.25 reads 25% on every face; omitted on any OTHER numeric type declares NO fixed width — the value keeps its natural precision, and a DECLARED scale: 0 (a year, a fiscal period, an ordinal) stays distinguishable from having declared nothing, so nothing is defaulted there. Consumers resolve the effective width by calling resolveFieldScale from @objectstack/spec/data, the single source for an absent scale: a renderer that spells its own fallback is a width no other face can see, and that is how one stored 0.25 came to read 25% on the read-only cell and 25.00% in the edit widget. On a percent field this is the number of decimal places of the PERCENTAGE-POINT value as displayed and entered — scale: 2 means 12.34% — and the STORED precision derives from the field's storage scale rather than being declared again: a fraction-stored percent (no max, or a max at or below 1) stores 12.34% as 0.1234 and is allowed scale + 2 decimal places at the write seam, while a whole-percent field (max above 1) stores the displayed number itself and is allowed exactly scale. number, rating and slider are allowed exactly scale. The upper bound is the platform's, not a policy: renderers turn scale into fraction digits through toFixed and Intl.NumberFormat's maximumFractionDigits, both of which throw a RangeError above 100 — so a larger declaration is unrenderable by any conforming consumer.
minnumberoptionalMinimum value. Checked on the WRITTEN value only — the same transition-gate class as requiredWhen: an UPDATE validates just the fields the payload carries, so a stored value below a bound declared later is never re-read and survives unrelated edits; only a write that carries an out-of-bound value is refused, and a repairing write is accepted. For an invariant re-checked on every write, declare a validations[] script rule instead.
maxnumberoptionalMaximum value. Checked on the WRITTEN value only — the same transition-gate class as min: a stored value above a bound declared later is never re-read and survives unrelated edits; only a write that carries an out-of-bound value is refused. For an invariant re-checked on every write, declare a validations[] script rule instead.
useGroupingbooleanoptionalDigit-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.
percentDisplayEnum<'bar' | 'plain'>optionalHow a percent field is displayed read-only (list cells, record page). Absent = the renderer default, a progress bar beside the percentage; bar = pin the progress bar; plain = the percentage as text alone, with no bar, for a rate or a probability rather than progress. Display only: the stored value, its validation and its decimal places (scale) are unchanged.
acceptstring[]optionalPermitted upload types for media fields, as MIME types or extensions (e.g. ["image/*", ".pdf"]). Offered to the file picker AND enforced on write.
maxSizeintegeroptionalMaximum 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; description?: string; color?: string; … }[]optionalStatic options for the option types. A select / radio field needs a non-empty list here or a picklist — with neither (or options: []) it is refused at parse.
pickliststringoptionalName of a shared picklist whose options this field offers — instead of options, never with it. Option types only (select, radio, multiselect, checkboxes, tags). A select / radio declares this or a non-empty options; with neither it is refused at parse.
referencestringoptionalTarget object name (snake_case) for lookup/master_detail fields. Required for relationship types. Used by $expand to resolve foreign key IDs into full objects. Never a stored-metadata table (sys_metadata, sys_metadata_history): their rows are served only through the metadata API, so the engine never hydrates a reference into one, and os validate, os build and the object save door refuse it. On a tree field it is optional and, if given, must be the declaring object's own name — the object schema refuses any other target, and writes the own name when it is left out.
referenceViastringoptionalDeclares 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.
referenceDeletedWhen{ field: string; value: string }optionalMarks the record a referenceVia pointer names as PLATFORM-DELETED on rows where a sibling select field holds one declared option — e.g. record_id with { field: 'cancel_reason', value: 'record_deleted' }. A renderer then draws a tombstone from that option's own label, reads nothing and links nothing. Valid only beside referenceVia; field must be a single-value select on the same object declaring inline options, and value one of its option values — any other shape is refused at parse.
referenceNameVisiblebooleanoptionalDeclared name exposure (lookup and user fields only). TRUE declares that a principal who can read the record carrying this field may see the referenced record's display name (the target object's nameField, else its displayNameField, else the derived title field) and id even when that principal cannot read the referenced record. Served on $expand: a target the reader is refused (the object's read gate or its row scope) answers { id, name, readRefused: true } (ReferenceNameOnlyValueSchema), per element on a multi-value field; an unexpanded read answers the stored id, as for every reader. Nothing else of the target: $expand on this field returns the same name and id only, the field's displayField does not widen it, and the name renders as text with no link to the target. A field-level rule on the name field still holds, and the name field is read only where nothing the security layer owns must be computed: the name is the Record # floor with the id when the reader may not read that field, it declares a maskingRule, it is a formula reading through another reference, an explicit nameField (or its displayNameField alias) points at a column that is neither title-typed nor autonumber, or no field-level answer can be had for the reader. A target with no resolvable or no non-empty name reads as the same floor. A principal who can read the target is served exactly what it is served without the key. Absent or false keeps the restricted-reference posture for a target the reader cannot read. Declared on the referencing field only; there is no target-object switch. Refused on any other type.
mailAssociationbooleanoptionalInbound mail association (email fields only): TRUE marks this field as identifying a correspondent. When a mailbox service ingests a message, it associates the message with every record of this object whose value in this field equals one of the message's participant addresses (From, Sender, Reply-To, To and Cc, plus those of a forwarded message it carries; ASCII case-insensitive; the receiving mailbox's own addresses excluded; only within the mailbox's organization). A message no record matches waits in the mailbox's unassociated pool. Refused on any other type. Takes effect only where a mailbox service is composed.
deleteBehaviorEnum<'set_null' | 'cascade' | 'restrict'>optional (default: "set_null")What happens if referenced record is deleted
inlineEditboolean | Enum<'grid' | 'form'>optionalEdit 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.
inlineTitlestringoptionalTitle for the inline master-detail grid
inlineColumns{ name: string; label?: string; type?: Enum<'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file'>; width?: number; … }[]optionalExplicit 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.
inlineAmountFieldstringoptionalNumeric child field summed for the inline grid total
relatedListboolean | 'primary'optionalShow this child collection as a related list on the parent's detail page (read-side mirror of inlineEdit). false = the child object is not shown on the parent record page; true/absent = shown as an auxiliary panel on the record page; 'primary' = part of the record's main content, shown as a full-width table in the record's detail body. Absent on a master_detail field that sets inlineEdit, the list is 'primary' by default; write true to keep it an auxiliary panel. 'primary' places a list and does not order it: the parent object's relatedLists orders the full-width tables and the auxiliary panels. The page layout is defined by 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.
relatedListTitlestringoptionalTitle for the detail-page related list
relatedListColumnsstring[]optionalExplicit 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.
relatedListFilteranyoptionalDeclarative 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.
displayFieldstringoptionalField shown as each candidate's label in the picker/popover (defaults to the referenced object's name/title).
descriptionFieldstringoptionalSecondary field shown under the label in the quick-select popover.
lookupColumns(string | { field: string; label?: string; width?: string; type?: string })[]optionalExplicit columns for the record-picker table; auto-derived from the referenced object when omitted.
lookupPageSizeintegeroptionalRows 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; orEmpty?: boolean }[]optionalBase filters restricting which records are selectable (e.g. only active). The structured, picker-honoured lookup filter. Each entry compares a column of the CANDIDATE record (field, on the referenced object) with value. A value may read the record being edited as { $record: "field" } or { $record: "lookup_field.field" } (at most one lookup hop). In a record form, whatever its layout, the picker sends that value in its place and re-queries whenever a referenced field changes; every other picker host leaves every { $record } entry out: inline edit on a record page, a record page's header or related list, an action's parameter dialog, and a picker with no single record being edited (a bulk action over selected rows). The referenced fields are implied: do not list them in dependsOn, which also scopes the candidate query by equality (dependsOn: ['quote_date'] adds quote_date = … to the query over the referenced object). While the value is empty or cannot be read (the hop's row or field does not come back, no object is named for the hop, or the host has no single-row reader), the entry is left out. A { $record } is the whole value, never a member of an in / notIn list. orEmpty: true also matches a candidate whose column is null. A { $record } that reaches a server unresolved is refused (INVALID_FILTER), never read as null: by name, naming the field and the path, when it arrives as the eq shorthand on a column other than a date, datetime or time column; any other operator, and eq on a date, datetime or time column, is refused earlier, in generic words. The picker narrows the choice only: a rule the save must enforce belongs on the server too.
dependsOn(string | { field: string; param?: string })[]optionalDeclares 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.
allowCreatebooleanoptionalAllow 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.
lookupAutofill{ target: string; source: string; overwrite?: boolean }[]optionalFields a pick in this lookup fills on the record being edited: each { target, source } pair copies the picked record's source field (a field of the reference object) into this object's target field — e.g. [{ target: 'unit_price', source: 'list_price' }] on a quote line's product lookup. Read wherever this field is picked: the record form, and a line-item grid column over it. OVERWRITE RULE — the default, overwrite absent or false: a pick never replaces a value somebody wrote. The target is filled only while it is empty or still holds the value an earlier pick filled in; a value the user typed, or one the record already stored, stays. Only a pair that declares overwrite: true replaces the target on every pick, whatever it holds. Client-side only: it fills the form, and nothing on the write path reads it — the filled value is saved as an ordinary write, and an import or API write that sets the lookup fills nothing. Only on a single-value lookup / master_detail. Each target is a field of this object other than this one, written by its author — not readonly, not computed (formula, summary, autonumber, or an expression) — and named once. Each source is a field of the referenced object that the record carries (not internal) and whose value the target can hold; os validate / os build judge the source. In a line-item grid the column key autofill still governs only the same-named copy and is unchanged; a declared pair takes its target out of that copy.
expressionstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalCEL expression the field's value is computed from, e.g. Frecord.amount * 0.1. On a formula field: computed on read, no column. On any other (stored) field: computed by the engine from the row the write stores and stored, so a client-sent value never stands and a summary can roll the column up — on every insert and every update by id (the stored row merged with the patch), and on a predicate update only when the patch moves an input (one value for every matched row, else the update is refused).
returnTypeEnum<'number' | 'text' | 'boolean' | 'date' | 'currency'>optionalInferred value type of a formula field (number/text/boolean/date/currency). currency: an amount of money, in the currency the formula's own currencyConfig declares, as a currency field declares it (no currencyConfig: dynamic, the tenant default currency).
summaryOperations{ object: string; field?: string; function: Enum<'count' | 'sum' | 'min' | 'max' | 'avg'>; relationshipField?: string; … }optionalRoll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted.
languagestringoptionalProgramming language for syntax highlighting (e.g., javascript, python, sql)
stepnumberoptionalStep increment for slider (default: 1)
currencyConfig{ currencyMode?: Enum<'dynamic' | 'fixed' | 'record'>; defaultCurrency?: string; currencyField?: string; homeAmount?: object }optionalWhich currency an amount is in: for a currency field, for a formula field whose returnType is currency, and for a summary that rolls up, through a master_detail, child amounts that follow this record's currency (currencyMode: 'record' naming this object's own code field). A summary that rolls up a stored home amount (a child field some homeAmount.field names) declares currencyMode: 'dynamic', with no defaultCurrency, and shows in the organization's home currency. A summary may otherwise declare only currencyMode: 'fixed', when every amount it reads is in that one currency; a count summary, any other dynamic summary and any other record roll-up are refused, by defineStack and by a single-object save or publish on a running server alike. Absent: dynamic mode, and no currency on a summary.
dimensionsintegeroptionalVector dimensionality (e.g., 1536 for OpenAI embeddings)
trackHistorybooleanoptionalRender this field's value changes as human-readable entries on the record activity timeline (ADR-0052 §5b). Opt-in per field.
groupstringoptionalField group name for organizing fields in forms and layouts (e.g., "contact_info", "billing", "system")
visibleWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — field is shown only when TRUE (else hidden). e.g. Precord.type == 'invoice'
readonlyWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — field is read-only when TRUE. e.g. Precord.status == 'paid'. Reads the bound record's OWN columns: the field level never reads a related record, so a read THROUGH a reference field (record.account.tier) faults on every row and refuses every update that writes the field — objectstack validate refuses it. Put such a check in a validations[] script rule, whose condition is read one hop through a reference.
requiredWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — field is required when TRUE. A TRANSITION GATE, not an invariant: the write is refused only when the merged record violates the requirement AND the pre-write record complied — so the write that flips the predicate TRUE, an INSERT born inside the gate, and a write that clears the cell are all refused, while a row that was already missing the value keeps passing unrelated edits and state moves that stay inside the gate (ADR-0113 non-regression: adding the rule to a deployed object never bricks existing rows). Need an invariant every write must satisfy instead ('X may never exceed Y') — declare a validations[] script rule, which re-checks the merged record with no exemption. Enforced by evaluateValidationRules. Reads the bound record's OWN columns: the field level never reads a related record, so a read THROUGH a reference field (record.account.tier) faults on every row and refuses every write that reaches it — objectstack validate refuses it; put such a check in a validations[] script rule, whose condition is read one hop through a reference. The only slot; the conditionalRequired alias was removed in protocol 17.
dueLikebooleanoptionalDeadline semantic (date / datetime only): TRUE declares this date a deadline, so a renderer may show relative overdue wording ("Overdue 3d") and an overdue colour once it has passed. Absent or FALSE: not a deadline — nothing is inferred from the field's name. Pair with settledWhen to say when the deadline is settled for a record. Refused on any other type. Display only: nothing on the write path reads it.
settledWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — the deadline is SETTLED while TRUE: no overdue wording or colour applies to this record, e.g. Precord.status == 'done'. Evaluated per record like visibleWhen, reading the record's own columns as record. Requires dueLike: true on a date / datetime field; refused otherwise. Display only: nothing on the write path reads it.
conditionalFormatting{ condition: string | object; style: Record<string, string> }[]optionalCell formatting rules for this field — [{ condition, style }], the same rule a list view's conditionalFormatting declares. In order, the first rule whose CEL condition holds applies its CSS style map to THIS FIELD'S CELL wherever the field renders (grid, kanban card, record page, related list, report cell); a list view's row rules style the row, and both may apply. The condition reads value (this field's value on the record) and record (the row) and no other root, e.g. Pvalue < 0 with style: { color: '#b91c1c' }; objectstack validate refuses a condition that does not parse or reads any other root. For presentation only — a semantic state such as a deadline's overdue is declared with dueLike / settledWhen instead. Display only: nothing on the write path reads it.
widgetstringoptionalForm widget override — names a registered field component (resolved as field:<widget>) to render this field instead of the type default. Degrades to the type renderer when unregistered. e.g. "object-ref", "filter-condition", "recipient-picker".
hiddenbooleanoptional (default: false)Hidden from default UI
internalbooleanoptionalNever return this field's value on the generic data path — the engine OMITS the key from find/findOne results, the 201 create body and the by-id update body, on the default projection AND when a client names the field in ?select=. Storage, filtering and indexing are untouched, so a server-side verifier can still match on the column and a purpose-built mint route can still return the value once at creation. The read protection for ADR-0100's third credential channel (auth-subsystem one-way hashes on text columns). Omission, not masking: a mask signals 'a value is set', which carries no information on a required column.
readonlybooleanoptional (default: false)Read-only — never editable in forms, AND server-enforced on BOTH write paths: a non-system write to this field is silently dropped from the payload on UPDATE and on INSERT (a create can no longer directly seed e.g. approval_status: "approved"), symmetric with readonlyWhen. A stripped INSERT field still falls back to its defaultValue. Exempt from the strip on BOTH paths: isSystem writes (seed replay, migration). Exempt on the UPDATE path ONLY: an opt-in "historical" import (preserveAudit) — which admits a whitelist (the audit/timestamp family plus author-declared business readonly fields). On INSERT the exemption does NOT apply: a non-system create that requests preserveAudit still has its readonly fields stripped, and is warned loudly that the exemption is UPDATE-only — replaying archival readonly facts on create requires a system context. A normal (non-system) import is NOT system-context and still strips.
requiredPermissionsstring[]optional[ADR-0066 D3] Capabilities required to read/edit this field (mask on read, deny on write; AND-gate).
maskingRuleEnum<'phone' | 'id_card' | 'bank_account' | 'email' | 'name'> | { keepHead: integer; keepTail: integer }optionalPartial masking rule enforced by the runtime FieldMasker (single channel — API, UI, export and AI context all see the same masked value). A named preset ('phone' 138**5678, 'id_card' keep 6+4, 'bank_account' keep last 4, 'email' j*@example.com, 'name' keep first char) or { keepHead, keepTail }. Masked for every non-system caller unless the field's requiredPermissions are ALL held (that evaluation is the unmask gate); a permission set marking the field non-readable still deletes it entirely. Deterministic, length-preserving output; masked callers cannot filter/sort/group/aggregate on the field.
ackPlaintextMaskingbooleanoptional[ADR-0100] Affirm a generic password field's plaintext-at-rest / masked-on-read contract is intended, silencing the author-time warning. No effect on non-password fields.
systembooleanoptionalAuto-injected system/audit field (e.g. created_at, updated_by, organization_id). Tools that surface system fields separately from author-declared business fields should branch on this flag.
sortablebooleanoptional (default: true)Whether field is sortable in list views
inlineHelpTextstringoptionalHelp text displayed below the field in forms
placeholderstringoptionalPlaceholder text rendered inside the empty input (the HTML placeholder attribute); disappears once a value is entered. Distinct from inlineHelpText (always-visible help rendered beside/under the input) and description (tooltip/developer documentation).
autonumberFormatstringoptional (default: "{0000}")Auto-number format: literal text + {0000} counter, {YYYY}/{MM}/{DD}/{YYYYMMDD} date tokens (business tz), and {field_name} interpolation. Counter resets per rendered prefix (e.g. AD{YYYYMMDD}``{0000} resets daily). Omitted on an autonumber field ⇒ the contract default {0000}, which every driver and the engine fallback read, so one field numbers alike on every backend.
externalIdbooleanoptional (default: false)Not read: no upsert, import or seed matches on this flag. A seed dataset names its match field in its own externalId; an import names it in the mapping's upsertKey.
renamedFromstring[]optionalEarlier keys of THIS field, written in the field-key grammar (lowercase snake_case), e.g. renamedFrom: ['company'] on a field now keyed account_name. On a package upgrade from a version that has one of these keys and not this one, the platform carries that column's data to this field instead of adding an empty column. A field renamed twice lists both earlier keys. Each entry once; never this field's own key; never a key another field of the same object still declares (that name is still in use); never an old key another field of the same object also claims. Read only by the schema sync and the package upgrade: no record read, write or query reads it, and the type of the old column is judged when the column is carried, not here. The schema sync (boot, os migrate apply, /marketplace/install-local) renames the old column to this key before it adds any column, and refuses before any write, naming the field, the old key and the reason, when the old key is a platform column, still a live field or claimed by two fields, when both columns or several old columns exist, when the old column would narrow under this type or this field stores no column (a formula), when an index cannot follow, when an object extension names a key its own package never added to the object (install-local), or when the driver renames no column.
_lockEnum<'none' | 'no-overlay' | 'no-delete' | 'full'>optionalItem-level lock — controls overlay & delete (ADR-0010).
_lockReasonstringoptionalHuman-readable reason shown when a write is refused by _lock.
_lockSourceEnum<'artifact' | 'package' | 'env-forced'>optionalLayer that set _lock (artifact | package | env-forced).
_provenanceEnum<'package' | 'org' | 'env-forced'>optionalOrigin of the item (package | org | env-forced).
_packageIdstringoptionalOwning package machine id.
_packageVersionstringoptionalOwning package version.
_lockDocsUrlstringoptionalOptional documentation link surfaced next to _lockReason.

ChangeSet

A versioned set of atomic schema migration operations

Properties

PropertyTypeRequiredDescription
idstring✅Unique identifier for this change set
namestring✅Human readable name for the migration
descriptionstringoptionalDetailed description of what this migration does
authorstringoptionalAuthor who created this migration
createdAtstringoptionalISO 8601 timestamp when the migration was created
dependencies{ migrationId: string; package?: string }[]optionalMigrations 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)[]optionalOperations to reverse this migration

Nested Shape: ChangeSet.dependencies[number]

Dependency reference to another migration that must run first

PropertyTypeRequiredDescription
migrationIdstring✅ID of the migration this depends on
packagestringoptionalPackage that owns the dependency migration

Nested Shape: ChangeSet.operations[number][type='add_field']

Add a new field to an existing object

PropertyTypeRequiredDescription
type'add_field'✅
objectNamestring✅Target object name
fieldNamestring✅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

Nested Shape: ChangeSet.operations[number][type='modify_field']

Modify properties of an existing field

PropertyTypeRequiredDescription
type'modify_field'✅
objectNamestring✅Target object name
fieldNamestring✅Name of the field to modify
changesRecord<string, any>✅Partial field definition updates

Nested Shape: ChangeSet.operations[number][type='remove_field']

Remove a field from an existing object

PropertyTypeRequiredDescription
type'remove_field'✅
objectNamestring✅Target object name
fieldNamestring✅Name of the field to remove

Nested Shape: ChangeSet.operations[number][type='create_object']

Create a new object

PropertyTypeRequiredDescription
type'create_object'✅
object{ name: string; label?: string; pluralLabel?: string; description?: string; … }✅Full object definition to create

Nested Shape: ChangeSet.operations[number][type='rename_object']

Rename an existing object

PropertyTypeRequiredDescription
type'rename_object'✅
oldNamestring✅Current object name
newNamestring✅New object name

Nested Shape: ChangeSet.operations[number][type='delete_object']

Delete an existing object

PropertyTypeRequiredDescription
type'delete_object'✅
objectNamestring✅Name of the object to delete

Nested Shape: ChangeSet.operations[number][type='execute_sql']

Execute a raw SQL statement

PropertyTypeRequiredDescription
type'execute_sql'✅
sqlstring✅Raw SQL statement to execute
descriptionstringoptionalHuman-readable description of the SQL

Nested Shape: ChangeSet.rollback[number][type='add_field']

Add a new field to an existing object

PropertyTypeRequiredDescription
type'add_field'✅
objectNamestring✅Target object name
fieldNamestring✅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

Nested Shape: ChangeSet.rollback[number][type='modify_field']

Modify properties of an existing field

PropertyTypeRequiredDescription
type'modify_field'✅
objectNamestring✅Target object name
fieldNamestring✅Name of the field to modify
changesRecord<string, any>✅Partial field definition updates

Nested Shape: ChangeSet.rollback[number][type='remove_field']

Remove a field from an existing object

PropertyTypeRequiredDescription
type'remove_field'✅
objectNamestring✅Target object name
fieldNamestring✅Name of the field to remove

Nested Shape: ChangeSet.rollback[number][type='create_object']

Create a new object

PropertyTypeRequiredDescription
type'create_object'✅
object{ name: string; label?: string; pluralLabel?: string; description?: string; … }✅Full object definition to create

Nested Shape: ChangeSet.rollback[number][type='rename_object']

Rename an existing object

PropertyTypeRequiredDescription
type'rename_object'✅
oldNamestring✅Current object name
newNamestring✅New object name

Nested Shape: ChangeSet.rollback[number][type='delete_object']

Delete an existing object

PropertyTypeRequiredDescription
type'delete_object'✅
objectNamestring✅Name of the object to delete

Nested Shape: ChangeSet.rollback[number][type='execute_sql']

Execute a raw SQL statement

PropertyTypeRequiredDescription
type'execute_sql'✅
sqlstring✅Raw SQL statement to execute
descriptionstringoptionalHuman-readable description of the SQL

CreateObjectOperation

Create a new object

Properties

PropertyTypeRequiredDescription
type'create_object'✅
object{ name: string; label?: string; pluralLabel?: string; description?: string; … }✅Full object definition to create

Nested Shape: CreateObjectOperation.object

PropertyTypeRequiredDescription
namestring✅Machine unique key (snake_case). Immutable.
labelstringoptionalHuman readable singular label (e.g. "Account")
pluralLabelstringoptionalHuman readable plural label (e.g. "Accounts")
descriptionstringoptionalDeveloper documentation / description
iconstringoptionalIcon name (Lucide/Material) for UI representation
isSystembooleanoptional (default: false)Is system object (protected from deletion; defaults its org-wide sharing to public when no sharingModel is set — plugin-sharing)
managedByEnum<'platform' | 'config' | 'system-data' | 'engine-owned' | 'append-only' | …>optionalLifecycle bucket — platform (user CRUD) | config (admin authored) | system-data (platform-defined schema, admin/user-writable data) | engine-owned (engine owns the lifecycle, no user writes) | append-only (audit) | synced (rows copied by a pull from a connector or federated source; read-only to members, and userActions cannot open a write) | better-auth (identity). UI clients honour the resolved affordance matrix.
ownershipEnum<'user' | 'business_unit' | 'org' | 'none'>optionalRecord-ownership model: user (default — injects reassignable owner_id plus owning_business_unit_id) | business_unit (unit-owned: owning_business_unit_id only, no owner_id) | org | none (no per-record owner, neither anchor). Distinct from the package own/extend contribution kind.
userActions{ create?: boolean | object; import?: boolean | object; edit?: boolean | object; delete?: boolean | object; … }optionalPer-object override of the resolved CRUD affordance matrix.
systemFieldsfalse | { tenant?: boolean; audit?: boolean }optionalOpt out of, or selectively disable, registry-level system-field auto-injection.
datasourcestringoptional (default: "default")Target Datasource ID. "default" is the primary DB.
external{ remoteName?: string; remoteSchema?: string; writable?: boolean; columnMap?: Record<string, string>; … }optionalRemote table binding for federated (external) objects.
fieldsRecord<string, { name?: string; label?: string; type: Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | …>; description?: string; … }>✅Field definitions map. Keys must be snake_case identifiers; "proto", "constructor" and "prototype" are refused, and so is the "sync" prefix, reserved for the platform's sync-in columns.
attachedOnReadRecord<string, Record<string, Enum<'number' | 'text' | 'boolean' | 'date'>>>optionalBlocks a service attaches to each row it serves, computed per caller on read and never stored: block name → { leaf key → value type (number | text | boolean | date) }. NOT a field — no column, form, list view, export, write path or translation bundle reads it, and a block name may not repeat a declared field name. Its reader is the shared build validator (@objectstack/lint over @objectstack/formula, as os build / os validate run it), and only where record is a row the service served: in an action's visible and disabled predicates record.<block> resolves, and record.<block>.<leaf> resolves only to a leaf the block declares. Every other expression site binds the stored row, which never carries a block — a flow condition, a validation rule, a field rule or formula, an option visibleWhen, a sharing rule, a hook — and refuses record.<block> as an unknown field.
indexes{ name?: string; fields: string[]; unique?: false | 'global' | 'organization' }[]optionalDatabase performance indexes
fieldGroups{ key: string; label: string; icon?: string; description?: string; … }[]optionalOrdered list of field groups (array order = display order). See ObjectFieldGroupSchema.
tenancy{ enabled: boolean; tenantField?: string }optionalMulti-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).
requiredPermissionsstring[] | { 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; … }optionalData lifecycle contract (ADR-0057): class + retention/ttl/rotation/archive policies enforced by the platform LifecycleService.
fileAccessDelegatestringoptionalKernel service that authorizes downloads of files owned by this object's media fields, and decides whether a reader who may not read sys_file sees their name, size and type in a record read of this object (asked once per owning record on each such read), instead of testing whether the caller can read the owning row. For objects whose access is mediated by a service (e.g. sys_approval_action → approvals). Fails closed.
schemaReadDelegatestringoptionalKernel service that decides whether a caller who may not read this object is still served its definition on the metadata API, projected by that caller's field-level security. For objects whose rows reach callers only through a service's own door (e.g. sys_approval_request → approvals); it opens no row. Fails closed.
validationsany[]optionalObject-level validation rules
activityMilestones{ field: string; value: string; summary: string; type?: string }[]optionalDeclarative semantic activity milestones — emit a templated timeline row when a field transitions into a value, no hook code (ADR-0052 §5b.2).
nameFieldstringoptional[ADR-0079] Canonical primary title field — the stored field used as the record display name (e.g. "name", "title").
displayNameFieldstringoptional[DEPRECATED → nameField] Field to use as the record display name (e.g., "name", "title"). Accepted as an alias for nameField.
titleFormatstring | { dialect: '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. An object definition that declares it is refused at the metadata save gate and by os validate; a stored object that carries it still parses and reads. Migrate a single-field title to nameField; a composite title that import, sort or search must match to a stored computed field (a non-formula field with an expression, computed and stored on every write) designated as nameField — a text formula designated as nameField stays legal for a title shown for display only. Placeholders may be written {{field}} or {field} — the title renderers treat the two as equivalent, normalizing {{field}} to {field} before substituting; neither spelling is judged at parse time.
imageFieldstringoptionalThe record's picture: names the field the record page header (record chrome) draws beside the title — one object-level declaration every record detail page reads, not a per-page header prop. Must name a field of this object whose type is image or avatar; any other name is refused. A record whose field is empty shows no picture (no initials or placeholder).
highlightFieldsstring[]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.
relatedListsstring[]optionalBusiness order of this object's related lists on its record page, most important first. Each entry is a child object name (e.g. "task"), or object.field when that child has more than one relationship to this object (e.g. "event.related_to"). Listed relationships come first in this order; unlisted ones follow in the derived order (owned master_detail children, then lookup children). An entry whose child is in the stack but has no inbound lookup / master_detail field to this object is refused everywhere. An entry whose child exists nowhere is refused by os validate / os build (which leave a sys_ / cloud_ / ai_ name to the runtime) and by a metadata write that names no package; a write into a package stores it, since a child outside the package may be a downstream package's object that points here, and the record page places nothing for it. It orders only: relatedList: false on the relationship still hides a list, and relatedList: 'primary' still places a list in the record's body, so the order applies among the body tables and among the side cards.
stageFieldstring | falseoptional[ADR-0085] Lifecycle stage field (linear/ordered), or false to declare the status field non-linear and suppress stage heuristics. Absent = heuristic detection allowed. When the named field carries options, it must be a single-value select / radio with inline options, each declaring its kind ('open' / 'won' / 'lost'); a picklist-backed or multi-value stage field is refused. A name that resolves to no declared field, or a field with no options, is not judged at parse.
editModeEnum<'modal' | 'page'>optionalEdit-interaction intent for records of this object: 'modal' opens the edit form as a dialog over the current view; 'page' navigates to a dedicated full-page edit route. Absent = the renderer picks its own default (objectui defaults to modal). Cross-renderer intent, not pixel styling (family).
listViewsRecord<string, { name?: string; label?: string | Record<string, string>; type?: Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | …>; data?: object | object | object; … }>optionalBuilt-in named list views (segmented tabs) shipped with the object schema — "views" mode, dropdown userFilters allowed, no page-only tabs (ADR-0047)
searchableFieldsstring[]optionalFields 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. Entries must name a STORED column: a virtual formula field is computed on read and materializes no column, so searching it can never match and it is refused — mirror the value onto a stored text field and declare that.
enable{ trackHistory?: boolean; searchable?: boolean; apiEnabled?: boolean; apiMethods?: Enum<'get' | 'list' | 'create' | 'update' | 'delete' | 'bulk'>[]; … }optionalEnabled system features modules
sharingModelEnum<'private' | 'public_read' | 'public_read_write' | 'controlled_by_parent'>optionalOrg-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).
sharing{ controlledByParent?: object }optionalPer-object sharing opt-ins that refine the org-wide default sharingModel declares. controlledByParent.ownerMayEdit: on a controlled_by_parent detail, the row's owner may update it with read access to the master (ADR-0055 §3 amendment). controlledByParent.writeRequiresMasterRead: anyone who reads the master may write the detail under the detail's own permissions.
defaultRowScope{ name: string; label?: string; description?: string; operation: Enum<'select' | 'insert' | 'update' | 'delete' | 'all'>; … }optionalThe object's default row scope: one row-level security policy, written like a permission set's rowLevelSecurity entry without object (the declaring object is implied; writing object is refused). The security plugin's row-policy collection, the one step every read, write and explain passes through, applies it when no permission set the caller holds carries a row policy for this object and the operation: a held policy for every object ('*') counts, while one for another operation, switched off, or outside the caller's positions does not. A policy an authored set carries for the object is used as authored, with this default not added to it; a principal whose superuser bypass skips row policies is unaffected; an object that declares none keeps the behaviour it has without the key. The default is judged like a held policy: its operation, positions and enabled decide where it applies, and a using the row-filter compiler cannot lower makes every read it governs return no rows, with one warning in the server log. os validate, os build and os lint judge this predicate as they judge a permission set's policy and report one that cannot lower; saving the object through the server does not run that check, so keep it inside the lowerable subset. Explain names an applied default as the object's own, not a permission set's.
membershipKeysRecord<string, { userField: string; valueField: string; filter?: string; label?: string; … }>optionalMembership keys this object defines, by name: each makes current_user.KEY the set of valueField values on this object's rows whose userField is the signed-in user and on which the optional filter holds, for a row-level security policy to read with in (e.g. supplier in current_user.portal_supplier_ids, declared on a supplier-contact object as portal_supplier_ids: { userField: 'user', valueField: 'supplier', filter: 'active == true' }). Declare a key on the one object whose rows define it; a key name is one request-wide name, so declaring it on two objects is refused, and the kernel's own names (id, organization_id, positions, org_user_ids, accessible_org_ids, email, queues) are refused. The set is read once per request, only when a policy reads the key, as a system read inside the caller's organization and regardless of what the caller may read on this object, so the caller needs no read on it; it holds at most 1,000 values, and a larger set, a failed read, a filter that does not compile for this object, or a key a registered membership resolver also owns makes every policy reading it match no rows. Whoever can write this object's rows can grant the key.
externalSharingModelneveroptional[REMOVED] object.externalSharingModel was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove) — it never had an effect: no request resolves an external principal, and the external rung of the authorization kernel (ADR-0095) admits explicitly shared rows only, never an org-wide default, so the value changed no answer for anyone. Delete the key. sharingModel is the one org-wide default; a principal reaches a row it does not own through an explicit share, and an anonymous reader through a share link (publicSharing). Run os migrate meta --from 17 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand.
publicSharing{ enabled?: boolean; allowedAudiences?: Enum<'public' | 'link_only' | 'signed_in' | 'email'>[]; allowedPermissions?: Enum<'view' | 'comment' | 'edit'>[]; maxExpiryDays?: integer; … }optionalPublic share-link policy (Notion/Figma-style link sharing)
actions{ name: string; label: string | Record<string, string>; description?: string | object | string | Record<string, string>; objectName?: string; … }[]optionalActions 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 }optionalPackage author protection block — lock policy for this object.
_lockEnum<'none' | 'no-overlay' | 'no-delete' | 'full'>optionalItem-level lock — controls overlay & delete (ADR-0010).
_lockReasonstringoptionalHuman-readable reason shown when a write is refused by _lock.
_lockSourceEnum<'artifact' | 'package' | 'env-forced'>optionalLayer that set _lock (artifact | package | env-forced).
_provenanceEnum<'package' | 'org' | 'env-forced'>optionalOrigin of the item (package | org | env-forced).
_packageIdstringoptionalOwning package machine id.
_packageVersionstringoptionalOwning package version.
_lockDocsUrlstringoptionalOptional documentation link surfaced next to _lockReason.

DataMigrationFlag

Deployment-level record that a data migration ran here and its self-check passed — the evidence gate consumers read instead of the platform version

Properties

PropertyTypeRequiredDescription
idstring✅Migration id (e.g. adr-0104-file-references) — one row per data migration
last_run_atstring✅When this migration last completed a gated (apply-mode) run on this deployment
verified_atstring | nulloptionalWhen the self-check last PASSED. Null/absent until it does — and cleared again by a later failing run, so a regression closes the gate
applied_atstring | nulloptionalWhen the backfill last ran in apply mode (writes enabled)
blockinginteger✅Blocking discrepancies reported by the last self-check. The gate requires 0
advisoryintegeroptionalAdvisory findings from the last run (external URLs, stale owners, …) — cost storage or need a modelling decision, never block the gate
detailsstringoptionalJSON-encoded counts from the last run, for diagnostics
deviation_observed_atstring | nulloptionalWhen this deployment last ADMITTED a value the verified contract rejects, via an OS_ALLOW_LAX_* escape hatch. Does not clear verified_at — it withdraws the irreversible half of what the certificate authorises
deviation_detailstring | nulloptionalJSON-encoded first counterexample behind deviation_observed_at (object, field, type, parse issue), for diagnostics
columns_moved_atstring | nulloptionalWhen this deployment last completed the COLUMN MOVE for this migration — the step that retypes the migrated columns and rewrites the values they hold into the new encoding. Separate evidence from applied_at and verified_at, which attest the backfill and its self-check only: a deployment can carry both and still store the legacy encoding. Null/absent says exactly that, and is an expected steady state rather than an error — it is what a consumer that cannot read this field must assume

DeleteObjectOperation

Delete an existing object

Properties

PropertyTypeRequiredDescription
type'delete_object'✅
objectNamestring✅Name of the object to delete

ExecuteSqlOperation

Execute a raw SQL statement

Properties

PropertyTypeRequiredDescription
type'execute_sql'✅
sqlstring✅Raw SQL statement to execute
descriptionstringoptionalHuman-readable description of the SQL

MigrationDependency

Dependency reference to another migration that must run first

Properties

PropertyTypeRequiredDescription
migrationIdstring✅ID of the migration this depends on
packagestringoptionalPackage that owns the dependency migration

MigrationJournalEvent

One event in a migration run journal — the durable trace that lets a killed run be resumed forward or compensated back, with rows proving which

Properties

PropertyTypeRequiredDescription
run_idstring✅Identifies one run. Rows are keyed (run_id, seq)
seqinteger✅Monotonic per-run sequence. Ordering authority — wall-clock timestamps can tie or skew
kindEnum<'run_started' | 'chunk_started' | 'chunk_done' | 'compensated' | 'run_done' | 'run_failed'>✅Event kind
migration_idstringoptionalThe named migration this run belongs to, when it has one — joins to sys_migration.id
plan_hashstringoptionalOn run_started: hash of the plan shape. A resume whose plan hash differs REFUSES rather than resuming a changed plan against an old journal
chunk_indexintegeroptionalOn chunk_started / chunk_done / compensated: the run-global chunk index
attemptintegeroptionalWhich attempt produced this event. attempt > 1 means a prior outcome was unknown and the callback was asked to recheck by natural key
detailstringoptionalJSON-encoded payload — the chunk plan on run_started, the error on run_failed / a failed compensation
created_atstringoptionalWall-clock stamp, for humans. Never the ordering authority — that is seq

MigrationOperation

Union Options

This schema accepts one of the following structures:

Option 1

Add a new field to an existing object

Type: add_field

Properties

PropertyTypeRequiredDescription
type'add_field'✅
objectNamestring✅Target object name
fieldNamestring✅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

Nested Shape: MigrationOperation[type='add_field'].field

PropertyTypeRequiredDescription
namestringoptionalMachine name (snake_case)
labelstringoptionalHuman readable label
typeEnum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | …>✅Field Data Type
descriptionstringoptionalTooltip/Help text
formatstringoptionalFree-form string whose meaning depends on the field type and on the reader. The spec declares NO vocabulary for it and checks nothing but that it is a string, so any string parses on any field type. On an autonumber field it is the record-number PATTERN — the shorthand that predates autonumberFormat, which wins when both are present: format: 'INV-{0000}' mints INV-0001 on both the query engine and the SQL driver, while a value carrying no {...} token is emitted as literal text with the bare counter appended (format: 'email' mints email1). Prefer autonumberFormat on a new field. On any other field type the server does not act on it: it picks no column type, coerces no value and runs no check from it. The Studio UI reads it as a display hint, in words and with defaults that its renderers own and declare. For example, the date and datetime cells read it as a display STYLE, and on a plain-text field the shared cell-renderer resolver reads a small set of words that promote the cell to a richer renderer, such as a link; each of those falls back silently to a default rendering when it does not recognise the word. To constrain a VALUE, use the field type (the write-time record validator's built-in email, url and phone checks key on type, never on this key) or a format validation rule, whose own format key is the closed set email | url | phone | json.
requiredbooleanoptional (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. 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 }optionalPhysical storage constraints (ADR-0113). Owns the DDL the write contract deliberately does not imply. Absent = no storage-level constraint requested.
searchablebooleanoptional (default: false)Search this field when its object declares no searchableFields. The set search scans, and the set a $searchFields override may name, is then the type-based default (the text-like and select columns) plus every field marked searchable: true, of any type except secret, password and vector, which stay excluded (a virtual formula field has no stored column, so it is never scanned either). false, the default, does not remove a field the type-based default already scans; to choose the set, declare searchableFields. When the object declares searchableFields, that list is the whole search set and this flag is not read (ADR-0061).
multiplebooleanoptional (default: false)Allow multiple values (Stores as Array/JSON). Declarable ONLY on the multi-capable types — select, lookup, user, file, image — and redundantly on the inherently-multi option types (multiselect, checkboxes, tags); multiple: true on any other type, radio included, is REFUSED at parse. A cleared optional multi-value field is stored as null, the same as one never set: an empty list [] or an empty string written to it stores null, and the rule binds every writer (cascade repair, form clears, API writes). Read null and [] alike as empty, as the is_empty filter ($empty) does, since a row stored before this rule can still hold []. On a required multi-value field the empty list is refused: required means a non-empty list.
uniqueboolean | 'global' | 'organization'optionalUnique 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'. Omitted ⇒ false, EXCEPT on an autonumber field, where omitted ⇒ 'organization' (an auto-number is a business identifier, so the platform makes it unique per organization by default — the same tenant-composite shape an explicit unique: true produces). To opt an autonumber field out, write unique: false explicitly — legitimate only for a display-only sequence that is not used to identify the record; the platform's duplicate scan (os migrate duplicates) still treats every autonumber field as an identifier.
defaultValueanyoptionalDefault 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.
maxLengthintegeroptionalMax 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. Checked on the WRITTEN value only (the min/max transition-gate class): a stored value longer than a bound declared later is never re-read and survives unrelated edits — only a write carrying an over-long value is refused.
minLengthintegeroptionalMin 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. Checked on the WRITTEN value only (the min/max transition-gate class): a stored value shorter than a bound declared later is never re-read and survives unrelated edits — only a write carrying a too-short value is refused.
valueDomainEnum<'iana_time_zone' | 'iso_4217_currency' | 'iso_3166_alpha2'>optionalStandard value domain the WRITTEN value must be a member of: iana_time_zone (an IANA/tzdb zone identifier such as UTC, Asia/Kolkata, Europe/Kyiv — membership is the Intl.DateTimeFormat probe, never the Intl.supportedValuesOf enumeration, which omits UTC), iso_4217_currency (an ISO 4217 alphabetic currency code, uppercase, e.g. CHF) or iso_3166_alpha2 (an ISO 3166-1 alpha-2 country code, uppercase, e.g. CH). The same closed vocabulary and the same membership predicate as a settings specifier's valueDomain. Only authorable on text — the one type whose stored value is a single plain string naming the member. Checked on the WRITTEN value only (the min/max/maxLength transition-gate class): a stored value outside a domain declared later is never re-read and survives unrelated edits — only a write carrying a non-member is refused, with the field error code value_domain. Reach for it precisely where a pattern cannot help: ^[A-Z]{2}$ admits ZZ, and Mars/Olympus is a shape-valid zone that does not exist.
rowsintegeroptionalHeight of the INLINE multiline editor, in text rows (positive integer — the HTML textarea rows attribute; fullscreen/dialog editor surfaces size themselves and ignore it). Only authorable on multiline editor types: textarea, markdown, html, richtext. Omit it for the widget default height.
precisionintegeroptionalTotal digits (non-negative integer) — the p of a DECIMAL(p, s): the digits of the value, integer and fraction together, counted at the field's decimal places, so precision: 5, scale: 2 holds up to 999.99 and refuses 1234.5 (1234.50 is 6 digits). Enforced on writes of number, currency, percent, rating and slider fields: a value that needs more digits is refused with field code max_precision, never rounded. Counted on the STORED value: at the declared scale when one applies, else at the value's own decimal places (leading zeros never count) — so on a currency field, where scale is refused, an amount's written decimals count toward the total; a fraction-stored percent is counted two places further right (scale + 2, or 2 with no scale), which makes the count that of the percentage-point value as displayed. Not decimal places (that is scale; a currency's are its CLDR fraction digits) and not a column size: every numeric column keeps the platform's fixed exact decimal whatever this declares. Not read on any other field type.
scaleintegeroptionalDecimal places (integer 0-100). Applies to number, percent, rating and slider fields, where it is enforced on writes, and to a formula field, whose computed result is rounded to it. REFUSED on a currency field — delete it there: a currency amount's decimal places are its currency's, so the currency's CLDR fraction digits decide how the amount displays, and a currency write's decimal places stay unconstrained. OMITTED on a percent field ⇒ 0 decimal places, so a stored 0.25 reads 25% on every face; omitted on any OTHER numeric type declares NO fixed width — the value keeps its natural precision, and a DECLARED scale: 0 (a year, a fiscal period, an ordinal) stays distinguishable from having declared nothing, so nothing is defaulted there. Consumers resolve the effective width by calling resolveFieldScale from @objectstack/spec/data, the single source for an absent scale: a renderer that spells its own fallback is a width no other face can see, and that is how one stored 0.25 came to read 25% on the read-only cell and 25.00% in the edit widget. On a percent field this is the number of decimal places of the PERCENTAGE-POINT value as displayed and entered — scale: 2 means 12.34% — and the STORED precision derives from the field's storage scale rather than being declared again: a fraction-stored percent (no max, or a max at or below 1) stores 12.34% as 0.1234 and is allowed scale + 2 decimal places at the write seam, while a whole-percent field (max above 1) stores the displayed number itself and is allowed exactly scale. number, rating and slider are allowed exactly scale. The upper bound is the platform's, not a policy: renderers turn scale into fraction digits through toFixed and Intl.NumberFormat's maximumFractionDigits, both of which throw a RangeError above 100 — so a larger declaration is unrenderable by any conforming consumer.
minnumberoptionalMinimum value. Checked on the WRITTEN value only — the same transition-gate class as requiredWhen: an UPDATE validates just the fields the payload carries, so a stored value below a bound declared later is never re-read and survives unrelated edits; only a write that carries an out-of-bound value is refused, and a repairing write is accepted. For an invariant re-checked on every write, declare a validations[] script rule instead.
maxnumberoptionalMaximum value. Checked on the WRITTEN value only — the same transition-gate class as min: a stored value above a bound declared later is never re-read and survives unrelated edits; only a write that carries an out-of-bound value is refused. For an invariant re-checked on every write, declare a validations[] script rule instead.
useGroupingbooleanoptionalDigit-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.
percentDisplayEnum<'bar' | 'plain'>optionalHow a percent field is displayed read-only (list cells, record page). Absent = the renderer default, a progress bar beside the percentage; bar = pin the progress bar; plain = the percentage as text alone, with no bar, for a rate or a probability rather than progress. Display only: the stored value, its validation and its decimal places (scale) are unchanged.
acceptstring[]optionalPermitted upload types for media fields, as MIME types or extensions (e.g. ["image/*", ".pdf"]). Offered to the file picker AND enforced on write.
maxSizeintegeroptionalMaximum 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; description?: string; color?: string; … }[]optionalStatic options for the option types. A select / radio field needs a non-empty list here or a picklist — with neither (or options: []) it is refused at parse.
pickliststringoptionalName of a shared picklist whose options this field offers — instead of options, never with it. Option types only (select, radio, multiselect, checkboxes, tags). A select / radio declares this or a non-empty options; with neither it is refused at parse.
referencestringoptionalTarget object name (snake_case) for lookup/master_detail fields. Required for relationship types. Used by $expand to resolve foreign key IDs into full objects. Never a stored-metadata table (sys_metadata, sys_metadata_history): their rows are served only through the metadata API, so the engine never hydrates a reference into one, and os validate, os build and the object save door refuse it. On a tree field it is optional and, if given, must be the declaring object's own name — the object schema refuses any other target, and writes the own name when it is left out.
referenceViastringoptionalDeclares 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.
referenceDeletedWhen{ field: string; value: string }optionalMarks the record a referenceVia pointer names as PLATFORM-DELETED on rows where a sibling select field holds one declared option — e.g. record_id with { field: 'cancel_reason', value: 'record_deleted' }. A renderer then draws a tombstone from that option's own label, reads nothing and links nothing. Valid only beside referenceVia; field must be a single-value select on the same object declaring inline options, and value one of its option values — any other shape is refused at parse.
referenceNameVisiblebooleanoptionalDeclared name exposure (lookup and user fields only). TRUE declares that a principal who can read the record carrying this field may see the referenced record's display name (the target object's nameField, else its displayNameField, else the derived title field) and id even when that principal cannot read the referenced record. Served on $expand: a target the reader is refused (the object's read gate or its row scope) answers { id, name, readRefused: true } (ReferenceNameOnlyValueSchema), per element on a multi-value field; an unexpanded read answers the stored id, as for every reader. Nothing else of the target: $expand on this field returns the same name and id only, the field's displayField does not widen it, and the name renders as text with no link to the target. A field-level rule on the name field still holds, and the name field is read only where nothing the security layer owns must be computed: the name is the Record # floor with the id when the reader may not read that field, it declares a maskingRule, it is a formula reading through another reference, an explicit nameField (or its displayNameField alias) points at a column that is neither title-typed nor autonumber, or no field-level answer can be had for the reader. A target with no resolvable or no non-empty name reads as the same floor. A principal who can read the target is served exactly what it is served without the key. Absent or false keeps the restricted-reference posture for a target the reader cannot read. Declared on the referencing field only; there is no target-object switch. Refused on any other type.
mailAssociationbooleanoptionalInbound mail association (email fields only): TRUE marks this field as identifying a correspondent. When a mailbox service ingests a message, it associates the message with every record of this object whose value in this field equals one of the message's participant addresses (From, Sender, Reply-To, To and Cc, plus those of a forwarded message it carries; ASCII case-insensitive; the receiving mailbox's own addresses excluded; only within the mailbox's organization). A message no record matches waits in the mailbox's unassociated pool. Refused on any other type. Takes effect only where a mailbox service is composed.
deleteBehaviorEnum<'set_null' | 'cascade' | 'restrict'>optional (default: "set_null")What happens if referenced record is deleted
inlineEditboolean | Enum<'grid' | 'form'>optionalEdit 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.
inlineTitlestringoptionalTitle for the inline master-detail grid
inlineColumns{ name: string; label?: string; type?: Enum<'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file'>; width?: number; … }[]optionalExplicit 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.
inlineAmountFieldstringoptionalNumeric child field summed for the inline grid total
relatedListboolean | 'primary'optionalShow this child collection as a related list on the parent's detail page (read-side mirror of inlineEdit). false = the child object is not shown on the parent record page; true/absent = shown as an auxiliary panel on the record page; 'primary' = part of the record's main content, shown as a full-width table in the record's detail body. Absent on a master_detail field that sets inlineEdit, the list is 'primary' by default; write true to keep it an auxiliary panel. 'primary' places a list and does not order it: the parent object's relatedLists orders the full-width tables and the auxiliary panels. The page layout is defined by 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.
relatedListTitlestringoptionalTitle for the detail-page related list
relatedListColumnsstring[]optionalExplicit 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.
relatedListFilteranyoptionalDeclarative 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.
displayFieldstringoptionalField shown as each candidate's label in the picker/popover (defaults to the referenced object's name/title).
descriptionFieldstringoptionalSecondary field shown under the label in the quick-select popover.
lookupColumns(string | { field: string; label?: string; width?: string; type?: string })[]optionalExplicit columns for the record-picker table; auto-derived from the referenced object when omitted.
lookupPageSizeintegeroptionalRows 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; orEmpty?: boolean }[]optionalBase filters restricting which records are selectable (e.g. only active). The structured, picker-honoured lookup filter. Each entry compares a column of the CANDIDATE record (field, on the referenced object) with value. A value may read the record being edited as { $record: "field" } or { $record: "lookup_field.field" } (at most one lookup hop). In a record form, whatever its layout, the picker sends that value in its place and re-queries whenever a referenced field changes; every other picker host leaves every { $record } entry out: inline edit on a record page, a record page's header or related list, an action's parameter dialog, and a picker with no single record being edited (a bulk action over selected rows). The referenced fields are implied: do not list them in dependsOn, which also scopes the candidate query by equality (dependsOn: ['quote_date'] adds quote_date = … to the query over the referenced object). While the value is empty or cannot be read (the hop's row or field does not come back, no object is named for the hop, or the host has no single-row reader), the entry is left out. A { $record } is the whole value, never a member of an in / notIn list. orEmpty: true also matches a candidate whose column is null. A { $record } that reaches a server unresolved is refused (INVALID_FILTER), never read as null: by name, naming the field and the path, when it arrives as the eq shorthand on a column other than a date, datetime or time column; any other operator, and eq on a date, datetime or time column, is refused earlier, in generic words. The picker narrows the choice only: a rule the save must enforce belongs on the server too.
dependsOn(string | { field: string; param?: string })[]optionalDeclares 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.
allowCreatebooleanoptionalAllow 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.
lookupAutofill{ target: string; source: string; overwrite?: boolean }[]optionalFields a pick in this lookup fills on the record being edited: each { target, source } pair copies the picked record's source field (a field of the reference object) into this object's target field — e.g. [{ target: 'unit_price', source: 'list_price' }] on a quote line's product lookup. Read wherever this field is picked: the record form, and a line-item grid column over it. OVERWRITE RULE — the default, overwrite absent or false: a pick never replaces a value somebody wrote. The target is filled only while it is empty or still holds the value an earlier pick filled in; a value the user typed, or one the record already stored, stays. Only a pair that declares overwrite: true replaces the target on every pick, whatever it holds. Client-side only: it fills the form, and nothing on the write path reads it — the filled value is saved as an ordinary write, and an import or API write that sets the lookup fills nothing. Only on a single-value lookup / master_detail. Each target is a field of this object other than this one, written by its author — not readonly, not computed (formula, summary, autonumber, or an expression) — and named once. Each source is a field of the referenced object that the record carries (not internal) and whose value the target can hold; os validate / os build judge the source. In a line-item grid the column key autofill still governs only the same-named copy and is unchanged; a declared pair takes its target out of that copy.
expressionstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalCEL expression the field's value is computed from, e.g. Frecord.amount * 0.1. On a formula field: computed on read, no column. On any other (stored) field: computed by the engine from the row the write stores and stored, so a client-sent value never stands and a summary can roll the column up — on every insert and every update by id (the stored row merged with the patch), and on a predicate update only when the patch moves an input (one value for every matched row, else the update is refused).
returnTypeEnum<'number' | 'text' | 'boolean' | 'date' | 'currency'>optionalInferred value type of a formula field (number/text/boolean/date/currency). currency: an amount of money, in the currency the formula's own currencyConfig declares, as a currency field declares it (no currencyConfig: dynamic, the tenant default currency).
summaryOperations{ object: string; field?: string; function: Enum<'count' | 'sum' | 'min' | 'max' | 'avg'>; relationshipField?: string; … }optionalRoll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted.
languagestringoptionalProgramming language for syntax highlighting (e.g., javascript, python, sql)
stepnumberoptionalStep increment for slider (default: 1)
currencyConfig{ currencyMode?: Enum<'dynamic' | 'fixed' | 'record'>; defaultCurrency?: string; currencyField?: string; homeAmount?: object }optionalWhich currency an amount is in: for a currency field, for a formula field whose returnType is currency, and for a summary that rolls up, through a master_detail, child amounts that follow this record's currency (currencyMode: 'record' naming this object's own code field). A summary that rolls up a stored home amount (a child field some homeAmount.field names) declares currencyMode: 'dynamic', with no defaultCurrency, and shows in the organization's home currency. A summary may otherwise declare only currencyMode: 'fixed', when every amount it reads is in that one currency; a count summary, any other dynamic summary and any other record roll-up are refused, by defineStack and by a single-object save or publish on a running server alike. Absent: dynamic mode, and no currency on a summary.
dimensionsintegeroptionalVector dimensionality (e.g., 1536 for OpenAI embeddings)
trackHistorybooleanoptionalRender this field's value changes as human-readable entries on the record activity timeline (ADR-0052 §5b). Opt-in per field.
groupstringoptionalField group name for organizing fields in forms and layouts (e.g., "contact_info", "billing", "system")
visibleWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — field is shown only when TRUE (else hidden). e.g. Precord.type == 'invoice'
readonlyWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — field is read-only when TRUE. e.g. Precord.status == 'paid'. Reads the bound record's OWN columns: the field level never reads a related record, so a read THROUGH a reference field (record.account.tier) faults on every row and refuses every update that writes the field — objectstack validate refuses it. Put such a check in a validations[] script rule, whose condition is read one hop through a reference.
requiredWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — field is required when TRUE. A TRANSITION GATE, not an invariant: the write is refused only when the merged record violates the requirement AND the pre-write record complied — so the write that flips the predicate TRUE, an INSERT born inside the gate, and a write that clears the cell are all refused, while a row that was already missing the value keeps passing unrelated edits and state moves that stay inside the gate (ADR-0113 non-regression: adding the rule to a deployed object never bricks existing rows). Need an invariant every write must satisfy instead ('X may never exceed Y') — declare a validations[] script rule, which re-checks the merged record with no exemption. Enforced by evaluateValidationRules. Reads the bound record's OWN columns: the field level never reads a related record, so a read THROUGH a reference field (record.account.tier) faults on every row and refuses every write that reaches it — objectstack validate refuses it; put such a check in a validations[] script rule, whose condition is read one hop through a reference. The only slot; the conditionalRequired alias was removed in protocol 17.
dueLikebooleanoptionalDeadline semantic (date / datetime only): TRUE declares this date a deadline, so a renderer may show relative overdue wording ("Overdue 3d") and an overdue colour once it has passed. Absent or FALSE: not a deadline — nothing is inferred from the field's name. Pair with settledWhen to say when the deadline is settled for a record. Refused on any other type. Display only: nothing on the write path reads it.
settledWhenstring | { dialect: Enum<'cel' | 'cron' | 'template'>; source: string; ast?: any; meta?: object }optionalPredicate (CEL) — the deadline is SETTLED while TRUE: no overdue wording or colour applies to this record, e.g. Precord.status == 'done'. Evaluated per record like visibleWhen, reading the record's own columns as record. Requires dueLike: true on a date / datetime field; refused otherwise. Display only: nothing on the write path reads it.
conditionalFormatting{ condition: string | object; style: Record<string, string> }[]optionalCell formatting rules for this field — [{ condition, style }], the same rule a list view's conditionalFormatting declares. In order, the first rule whose CEL condition holds applies its CSS style map to THIS FIELD'S CELL wherever the field renders (grid, kanban card, record page, related list, report cell); a list view's row rules style the row, and both may apply. The condition reads value (this field's value on the record) and record (the row) and no other root, e.g. Pvalue < 0 with style: { color: '#b91c1c' }; objectstack validate refuses a condition that does not parse or reads any other root. For presentation only — a semantic state such as a deadline's overdue is declared with dueLike / settledWhen instead. Display only: nothing on the write path reads it.
widgetstringoptionalForm widget override — names a registered field component (resolved as field:<widget>) to render this field instead of the type default. Degrades to the type renderer when unregistered. e.g. "object-ref", "filter-condition", "recipient-picker".
hiddenbooleanoptional (default: false)Hidden from default UI
internalbooleanoptionalNever return this field's value on the generic data path — the engine OMITS the key from find/findOne results, the 201 create body and the by-id update body, on the default projection AND when a client names the field in ?select=. Storage, filtering and indexing are untouched, so a server-side verifier can still match on the column and a purpose-built mint route can still return the value once at creation. The read protection for ADR-0100's third credential channel (auth-subsystem one-way hashes on text columns). Omission, not masking: a mask signals 'a value is set', which carries no information on a required column.
readonlybooleanoptional (default: false)Read-only — never editable in forms, AND server-enforced on BOTH write paths: a non-system write to this field is silently dropped from the payload on UPDATE and on INSERT (a create can no longer directly seed e.g. approval_status: "approved"), symmetric with readonlyWhen. A stripped INSERT field still falls back to its defaultValue. Exempt from the strip on BOTH paths: isSystem writes (seed replay, migration). Exempt on the UPDATE path ONLY: an opt-in "historical" import (preserveAudit) — which admits a whitelist (the audit/timestamp family plus author-declared business readonly fields). On INSERT the exemption does NOT apply: a non-system create that requests preserveAudit still has its readonly fields stripped, and is warned loudly that the exemption is UPDATE-only — replaying archival readonly facts on create requires a system context. A normal (non-system) import is NOT system-context and still strips.
requiredPermissionsstring[]optional[ADR-0066 D3] Capabilities required to read/edit this field (mask on read, deny on write; AND-gate).
maskingRuleEnum<'phone' | 'id_card' | 'bank_account' | 'email' | 'name'> | { keepHead: integer; keepTail: integer }optionalPartial masking rule enforced by the runtime FieldMasker (single channel — API, UI, export and AI context all see the same masked value). A named preset ('phone' 138**5678, 'id_card' keep 6+4, 'bank_account' keep last 4, 'email' j*@example.com, 'name' keep first char) or { keepHead, keepTail }. Masked for every non-system caller unless the field's requiredPermissions are ALL held (that evaluation is the unmask gate); a permission set marking the field non-readable still deletes it entirely. Deterministic, length-preserving output; masked callers cannot filter/sort/group/aggregate on the field.
ackPlaintextMaskingbooleanoptional[ADR-0100] Affirm a generic password field's plaintext-at-rest / masked-on-read contract is intended, silencing the author-time warning. No effect on non-password fields.
systembooleanoptionalAuto-injected system/audit field (e.g. created_at, updated_by, organization_id). Tools that surface system fields separately from author-declared business fields should branch on this flag.
sortablebooleanoptional (default: true)Whether field is sortable in list views
inlineHelpTextstringoptionalHelp text displayed below the field in forms
placeholderstringoptionalPlaceholder text rendered inside the empty input (the HTML placeholder attribute); disappears once a value is entered. Distinct from inlineHelpText (always-visible help rendered beside/under the input) and description (tooltip/developer documentation).
autonumberFormatstringoptional (default: "{0000}")Auto-number format: literal text + {0000} counter, {YYYY}/{MM}/{DD}/{YYYYMMDD} date tokens (business tz), and {field_name} interpolation. Counter resets per rendered prefix (e.g. AD{YYYYMMDD}``{0000} resets daily). Omitted on an autonumber field ⇒ the contract default {0000}, which every driver and the engine fallback read, so one field numbers alike on every backend.
externalIdbooleanoptional (default: false)Not read: no upsert, import or seed matches on this flag. A seed dataset names its match field in its own externalId; an import names it in the mapping's upsertKey.
renamedFromstring[]optionalEarlier keys of THIS field, written in the field-key grammar (lowercase snake_case), e.g. renamedFrom: ['company'] on a field now keyed account_name. On a package upgrade from a version that has one of these keys and not this one, the platform carries that column's data to this field instead of adding an empty column. A field renamed twice lists both earlier keys. Each entry once; never this field's own key; never a key another field of the same object still declares (that name is still in use); never an old key another field of the same object also claims. Read only by the schema sync and the package upgrade: no record read, write or query reads it, and the type of the old column is judged when the column is carried, not here. The schema sync (boot, os migrate apply, /marketplace/install-local) renames the old column to this key before it adds any column, and refuses before any write, naming the field, the old key and the reason, when the old key is a platform column, still a live field or claimed by two fields, when both columns or several old columns exist, when the old column would narrow under this type or this field stores no column (a formula), when an index cannot follow, when an object extension names a key its own package never added to the object (install-local), or when the driver renames no column.
_lockEnum<'none' | 'no-overlay' | 'no-delete' | 'full'>optionalItem-level lock — controls overlay & delete (ADR-0010).
_lockReasonstringoptionalHuman-readable reason shown when a write is refused by _lock.
_lockSourceEnum<'artifact' | 'package' | 'env-forced'>optionalLayer that set _lock (artifact | package | env-forced).
_provenanceEnum<'package' | 'org' | 'env-forced'>optionalOrigin of the item (package | org | env-forced).
_packageIdstringoptionalOwning package machine id.
_packageVersionstringoptionalOwning package version.
_lockDocsUrlstringoptionalOptional documentation link surfaced next to _lockReason.

Option 2

Modify properties of an existing field

Type: modify_field

Properties

PropertyTypeRequiredDescription
type'modify_field'✅
objectNamestring✅Target object name
fieldNamestring✅Name of the field to modify
changesRecord<string, any>✅Partial field definition updates

Option 3

Remove a field from an existing object

Type: remove_field

Properties

PropertyTypeRequiredDescription
type'remove_field'✅
objectNamestring✅Target object name
fieldNamestring✅Name of the field to remove

Option 4

Create a new object

Type: create_object

Properties

PropertyTypeRequiredDescription
type'create_object'✅
object{ name: string; label?: string; pluralLabel?: string; description?: string; … }✅Full object definition to create

Nested Shape: MigrationOperation[type='create_object'].object

PropertyTypeRequiredDescription
namestring✅Machine unique key (snake_case). Immutable.
labelstringoptionalHuman readable singular label (e.g. "Account")
pluralLabelstringoptionalHuman readable plural label (e.g. "Accounts")
descriptionstringoptionalDeveloper documentation / description
iconstringoptionalIcon name (Lucide/Material) for UI representation
isSystembooleanoptional (default: false)Is system object (protected from deletion; defaults its org-wide sharing to public when no sharingModel is set — plugin-sharing)
managedByEnum<'platform' | 'config' | 'system-data' | 'engine-owned' | 'append-only' | …>optionalLifecycle bucket — platform (user CRUD) | config (admin authored) | system-data (platform-defined schema, admin/user-writable data) | engine-owned (engine owns the lifecycle, no user writes) | append-only (audit) | synced (rows copied by a pull from a connector or federated source; read-only to members, and userActions cannot open a write) | better-auth (identity). UI clients honour the resolved affordance matrix.
ownershipEnum<'user' | 'business_unit' | 'org' | 'none'>optionalRecord-ownership model: user (default — injects reassignable owner_id plus owning_business_unit_id) | business_unit (unit-owned: owning_business_unit_id only, no owner_id) | org | none (no per-record owner, neither anchor). Distinct from the package own/extend contribution kind.
userActions{ create?: boolean | object; import?: boolean | object; edit?: boolean | object; delete?: boolean | object; … }optionalPer-object override of the resolved CRUD affordance matrix.
systemFieldsfalse | { tenant?: boolean; audit?: boolean }optionalOpt out of, or selectively disable, registry-level system-field auto-injection.
datasourcestringoptional (default: "default")Target Datasource ID. "default" is the primary DB.
external{ remoteName?: string; remoteSchema?: string; writable?: boolean; columnMap?: Record<string, string>; … }optionalRemote table binding for federated (external) objects.
fieldsRecord<string, { name?: string; label?: string; type: Enum<'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'secret' | …>; description?: string; … }>✅Field definitions map. Keys must be snake_case identifiers; "proto", "constructor" and "prototype" are refused, and so is the "sync" prefix, reserved for the platform's sync-in columns.
attachedOnReadRecord<string, Record<string, Enum<'number' | 'text' | 'boolean' | 'date'>>>optionalBlocks a service attaches to each row it serves, computed per caller on read and never stored: block name → { leaf key → value type (number | text | boolean | date) }. NOT a field — no column, form, list view, export, write path or translation bundle reads it, and a block name may not repeat a declared field name. Its reader is the shared build validator (@objectstack/lint over @objectstack/formula, as os build / os validate run it), and only where record is a row the service served: in an action's visible and disabled predicates record.<block> resolves, and record.<block>.<leaf> resolves only to a leaf the block declares. Every other expression site binds the stored row, which never carries a block — a flow condition, a validation rule, a field rule or formula, an option visibleWhen, a sharing rule, a hook — and refuses record.<block> as an unknown field.
indexes{ name?: string; fields: string[]; unique?: false | 'global' | 'organization' }[]optionalDatabase performance indexes
fieldGroups{ key: string; label: string; icon?: string; description?: string; … }[]optionalOrdered list of field groups (array order = display order). See ObjectFieldGroupSchema.
tenancy{ enabled: boolean; tenantField?: string }optionalMulti-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).
requiredPermissionsstring[] | { 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; … }optionalData lifecycle contract (ADR-0057): class + retention/ttl/rotation/archive policies enforced by the platform LifecycleService.
fileAccessDelegatestringoptionalKernel service that authorizes downloads of files owned by this object's media fields, and decides whether a reader who may not read sys_file sees their name, size and type in a record read of this object (asked once per owning record on each such read), instead of testing whether the caller can read the owning row. For objects whose access is mediated by a service (e.g. sys_approval_action → approvals). Fails closed.
schemaReadDelegatestringoptionalKernel service that decides whether a caller who may not read this object is still served its definition on the metadata API, projected by that caller's field-level security. For objects whose rows reach callers only through a service's own door (e.g. sys_approval_request → approvals); it opens no row. Fails closed.
validationsany[]optionalObject-level validation rules
activityMilestones{ field: string; value: string; summary: string; type?: string }[]optionalDeclarative semantic activity milestones — emit a templated timeline row when a field transitions into a value, no hook code (ADR-0052 §5b.2).
nameFieldstringoptional[ADR-0079] Canonical primary title field — the stored field used as the record display name (e.g. "name", "title").
displayNameFieldstringoptional[DEPRECATED → nameField] Field to use as the record display name (e.g., "name", "title"). Accepted as an alias for nameField.
titleFormatstring | { dialect: '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. An object definition that declares it is refused at the metadata save gate and by os validate; a stored object that carries it still parses and reads. Migrate a single-field title to nameField; a composite title that import, sort or search must match to a stored computed field (a non-formula field with an expression, computed and stored on every write) designated as nameField — a text formula designated as nameField stays legal for a title shown for display only. Placeholders may be written {{field}} or {field} — the title renderers treat the two as equivalent, normalizing {{field}} to {field} before substituting; neither spelling is judged at parse time.
imageFieldstringoptionalThe record's picture: names the field the record page header (record chrome) draws beside the title — one object-level declaration every record detail page reads, not a per-page header prop. Must name a field of this object whose type is image or avatar; any other name is refused. A record whose field is empty shows no picture (no initials or placeholder).
highlightFieldsstring[]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.
relatedListsstring[]optionalBusiness order of this object's related lists on its record page, most important first. Each entry is a child object name (e.g. "task"), or object.field when that child has more than one relationship to this object (e.g. "event.related_to"). Listed relationships come first in this order; unlisted ones follow in the derived order (owned master_detail children, then lookup children). An entry whose child is in the stack but has no inbound lookup / master_detail field to this object is refused everywhere. An entry whose child exists nowhere is refused by os validate / os build (which leave a sys_ / cloud_ / ai_ name to the runtime) and by a metadata write that names no package; a write into a package stores it, since a child outside the package may be a downstream package's object that points here, and the record page places nothing for it. It orders only: relatedList: false on the relationship still hides a list, and relatedList: 'primary' still places a list in the record's body, so the order applies among the body tables and among the side cards.
stageFieldstring | falseoptional[ADR-0085] Lifecycle stage field (linear/ordered), or false to declare the status field non-linear and suppress stage heuristics. Absent = heuristic detection allowed. When the named field carries options, it must be a single-value select / radio with inline options, each declaring its kind ('open' / 'won' / 'lost'); a picklist-backed or multi-value stage field is refused. A name that resolves to no declared field, or a field with no options, is not judged at parse.
editModeEnum<'modal' | 'page'>optionalEdit-interaction intent for records of this object: 'modal' opens the edit form as a dialog over the current view; 'page' navigates to a dedicated full-page edit route. Absent = the renderer picks its own default (objectui defaults to modal). Cross-renderer intent, not pixel styling (family).
listViewsRecord<string, { name?: string; label?: string | Record<string, string>; type?: Enum<'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | …>; data?: object | object | object; … }>optionalBuilt-in named list views (segmented tabs) shipped with the object schema — "views" mode, dropdown userFilters allowed, no page-only tabs (ADR-0047)
searchableFieldsstring[]optionalFields 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. Entries must name a STORED column: a virtual formula field is computed on read and materializes no column, so searching it can never match and it is refused — mirror the value onto a stored text field and declare that.
enable{ trackHistory?: boolean; searchable?: boolean; apiEnabled?: boolean; apiMethods?: Enum<'get' | 'list' | 'create' | 'update' | 'delete' | 'bulk'>[]; … }optionalEnabled system features modules
sharingModelEnum<'private' | 'public_read' | 'public_read_write' | 'controlled_by_parent'>optionalOrg-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).
sharing{ controlledByParent?: object }optionalPer-object sharing opt-ins that refine the org-wide default sharingModel declares. controlledByParent.ownerMayEdit: on a controlled_by_parent detail, the row's owner may update it with read access to the master (ADR-0055 §3 amendment). controlledByParent.writeRequiresMasterRead: anyone who reads the master may write the detail under the detail's own permissions.
defaultRowScope{ name: string; label?: string; description?: string; operation: Enum<'select' | 'insert' | 'update' | 'delete' | 'all'>; … }optionalThe object's default row scope: one row-level security policy, written like a permission set's rowLevelSecurity entry without object (the declaring object is implied; writing object is refused). The security plugin's row-policy collection, the one step every read, write and explain passes through, applies it when no permission set the caller holds carries a row policy for this object and the operation: a held policy for every object ('*') counts, while one for another operation, switched off, or outside the caller's positions does not. A policy an authored set carries for the object is used as authored, with this default not added to it; a principal whose superuser bypass skips row policies is unaffected; an object that declares none keeps the behaviour it has without the key. The default is judged like a held policy: its operation, positions and enabled decide where it applies, and a using the row-filter compiler cannot lower makes every read it governs return no rows, with one warning in the server log. os validate, os build and os lint judge this predicate as they judge a permission set's policy and report one that cannot lower; saving the object through the server does not run that check, so keep it inside the lowerable subset. Explain names an applied default as the object's own, not a permission set's.
membershipKeysRecord<string, { userField: string; valueField: string; filter?: string; label?: string; … }>optionalMembership keys this object defines, by name: each makes current_user.KEY the set of valueField values on this object's rows whose userField is the signed-in user and on which the optional filter holds, for a row-level security policy to read with in (e.g. supplier in current_user.portal_supplier_ids, declared on a supplier-contact object as portal_supplier_ids: { userField: 'user', valueField: 'supplier', filter: 'active == true' }). Declare a key on the one object whose rows define it; a key name is one request-wide name, so declaring it on two objects is refused, and the kernel's own names (id, organization_id, positions, org_user_ids, accessible_org_ids, email, queues) are refused. The set is read once per request, only when a policy reads the key, as a system read inside the caller's organization and regardless of what the caller may read on this object, so the caller needs no read on it; it holds at most 1,000 values, and a larger set, a failed read, a filter that does not compile for this object, or a key a registered membership resolver also owns makes every policy reading it match no rows. Whoever can write this object's rows can grant the key.
externalSharingModelneveroptional[REMOVED] object.externalSharingModel was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove) — it never had an effect: no request resolves an external principal, and the external rung of the authorization kernel (ADR-0095) admits explicitly shared rows only, never an org-wide default, so the value changed no answer for anyone. Delete the key. sharingModel is the one org-wide default; a principal reaches a row it does not own through an explicit share, and an anonymous reader through a share link (publicSharing). Run os migrate meta --from 17 to list the mechanical edits for existing sources; --write applies the ones it can prove, and you apply the rest by hand.
publicSharing{ enabled?: boolean; allowedAudiences?: Enum<'public' | 'link_only' | 'signed_in' | 'email'>[]; allowedPermissions?: Enum<'view' | 'comment' | 'edit'>[]; maxExpiryDays?: integer; … }optionalPublic share-link policy (Notion/Figma-style link sharing)
actions{ name: string; label: string | Record<string, string>; description?: string | object | string | Record<string, string>; objectName?: string; … }[]optionalActions 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 }optionalPackage author protection block — lock policy for this object.
_lockEnum<'none' | 'no-overlay' | 'no-delete' | 'full'>optionalItem-level lock — controls overlay & delete (ADR-0010).
_lockReasonstringoptionalHuman-readable reason shown when a write is refused by _lock.
_lockSourceEnum<'artifact' | 'package' | 'env-forced'>optionalLayer that set _lock (artifact | package | env-forced).
_provenanceEnum<'package' | 'org' | 'env-forced'>optionalOrigin of the item (package | org | env-forced).
_packageIdstringoptionalOwning package machine id.
_packageVersionstringoptionalOwning package version.
_lockDocsUrlstringoptionalOptional documentation link surfaced next to _lockReason.

Option 5

Rename an existing object

Type: rename_object

Properties

PropertyTypeRequiredDescription
type'rename_object'✅
oldNamestring✅Current object name
newNamestring✅New object name

Option 6

Delete an existing object

Type: delete_object

Properties

PropertyTypeRequiredDescription
type'delete_object'✅
objectNamestring✅Name of the object to delete

Option 7

Execute a raw SQL statement

Type: execute_sql

Properties

PropertyTypeRequiredDescription
type'execute_sql'✅
sqlstring✅Raw SQL statement to execute
descriptionstringoptionalHuman-readable description of the SQL


ModifyFieldOperation

Modify properties of an existing field

Properties

PropertyTypeRequiredDescription
type'modify_field'✅
objectNamestring✅Target object name
fieldNamestring✅Name of the field to modify
changesRecord<string, any>✅Partial field definition updates

OrganizationOwnershipBirthMarker

Birth marker of a datastore created from empty: the ownership shape generation it was born in

Properties

PropertyTypeRequiredDescription
shapeGenerationinteger✅The organization-ownership shape generation the store was created in; the only field the boot guard decides on
platformVersionstring✅The exact platform version that created the store (provenance only, never compared)
commitstringoptionalThe source commit of that build, when known (provenance only)
createdAtstring✅When the guard observed the store created from empty

RemoveFieldOperation

Remove a field from an existing object

Properties

PropertyTypeRequiredDescription
type'remove_field'✅
objectNamestring✅Target object name
fieldNamestring✅Name of the field to remove

RenameObjectOperation

Rename an existing object

Properties

PropertyTypeRequiredDescription
type'rename_object'✅
oldNamestring✅Current object name
newNamestring✅New object name

On this page

TypeScript UsageAddFieldOperationPropertiesNested Shape: AddFieldOperation.fieldChangeSetPropertiesNested Shape: ChangeSet.dependencies[number]Nested Shape: ChangeSet.operations[number][type='add_field']Nested Shape: ChangeSet.operations[number][type='modify_field']Nested Shape: ChangeSet.operations[number][type='remove_field']Nested Shape: ChangeSet.operations[number][type='create_object']Nested Shape: ChangeSet.operations[number][type='rename_object']Nested Shape: ChangeSet.operations[number][type='delete_object']Nested Shape: ChangeSet.operations[number][type='execute_sql']Nested Shape: ChangeSet.rollback[number][type='add_field']Nested Shape: ChangeSet.rollback[number][type='modify_field']Nested Shape: ChangeSet.rollback[number][type='remove_field']Nested Shape: ChangeSet.rollback[number][type='create_object']Nested Shape: ChangeSet.rollback[number][type='rename_object']Nested Shape: ChangeSet.rollback[number][type='delete_object']Nested Shape: ChangeSet.rollback[number][type='execute_sql']CreateObjectOperationPropertiesNested Shape: CreateObjectOperation.objectDataMigrationFlagPropertiesDeleteObjectOperationPropertiesExecuteSqlOperationPropertiesMigrationDependencyPropertiesMigrationJournalEventPropertiesMigrationOperationUnion OptionsOption 1PropertiesNested Shape: MigrationOperation[type='add_field'].fieldOption 2PropertiesOption 3PropertiesOption 4PropertiesNested Shape: MigrationOperation[type='create_object'].objectOption 5PropertiesOption 6PropertiesOption 7PropertiesModifyFieldOperationPropertiesOrganizationOwnershipBirthMarkerPropertiesRemoveFieldOperationPropertiesRenameObjectOperationProperties