Skip to content

Commit a566c0c

Browse files
committed
docs(spec): a cleared optional multi-value field is stored as null
Amend the FieldSchema `multiple` and `required` doc blocks and the `multiple` describe to the ruled empty representation: a cleared optional multi-value field stores null at the write door, `[]` and `''` store null, `required` still means a non-empty list, and the `$empty` table is unchanged. Claude-Session: https://claude.ai/code/session_01WGufzeW5cprrZRccVNgPFr Co-authored-by: Claude <noreply@anthropic.com>
1 parent 1c1a5d4 commit a566c0c

3 files changed

Lines changed: 40 additions & 15 deletions

File tree

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
docs(spec): a cleared optional multi-value field is stored as `null`, the same as one never set; `FieldSchema`'s `multiple` and `required` docs now say so
6+
7+
Clause-②: yes
8+
Metadata-protocol: semantic
9+
10+
`FieldSchema.multiple` documented that an emptied multi-value lookup reads back as `[]`, never `null`, for every writer, and `required` leaned on that. The rule is now the other way round for optional columns.
11+
12+
- **Now.** A cleared optional multi-value field (`multiselect`, `checkboxes`, `tags`, and `select`, `lookup`, `user`, `file` or `image` with `multiple: true`) is stored as `null` at the engine's write door, the same as a field never set, whether or not a unique constraint covers it. `[]` and `''` written to such a column store `null`. The rule binds every writer: cascade repair, form clears and API writes.
13+
- **Reading.** Treat `null` and `[]` alike as empty. The `is_empty` filter (`$empty`) already does, and its table is unchanged. A row stored before this rule can still hold `[]`.
14+
- **Unchanged.** `required` on a multi-value field still means a non-empty list: `[]` is refused, as is `null`.
15+
- **This change is documentation.** The `multiple` and `required` descriptions (and the generated field reference) state the rule. The write-door change that applies it to `[]` and `''` ships separately, and stored `[]` values are cleaned by a separate `os migrate` data step.

‎packages/spec/src/data/field.zod.ts‎

Lines changed: 23 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1313,11 +1313,12 @@ export const FieldSchema = lazySchema(() => {
13131313
*
13141314
* On a multi-value lookup (`multiple: true`), `required` means NON-EMPTY
13151315
* array: an emptied required set fails validation loudly — `[]` does not
1316-
* satisfy `required` (#9447, maintainer ruling 2026-08-18). The empty set is
1317-
* always representable (it reads back as `[]`, never `null` — see
1318-
* `multiple`), so the required check judges emptiness, not absence. The
1319-
* describe is form help in Studio and carries the rule, not the ruling date
1320-
* (#22093).
1316+
* satisfy `required` (#9447, maintainer ruling 2026-08-18; this half stands
1317+
* under ruling A on #29343, record 6591577985). An emptied OPTIONAL
1318+
* multi-value field is stored as `null`, the same as one never set (see
1319+
* `multiple`), so the required check judges emptiness: `null` and `[]` both
1320+
* fail it. The describe is form help in Studio and carries the rule, not the
1321+
* ruling date (#22093).
13211322
*/
13221323
required: z.boolean().default(false).describe('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.'),
13231324

@@ -1354,21 +1355,29 @@ export const FieldSchema = lazySchema(() => {
13541355
+ 'is the whole search set and this flag is not read (ADR-0061).',
13551356
),
13561357
/**
1357-
* Multi-value empty representation (#9447, maintainer ruling 2026-08-18):
1358-
* an emptied multi-value lookup reads back as `[]`, never `null`. This
1359-
* binds the field's empty representation for EVERY writer — cascade repair
1360-
* (`set_null` member removal), form clears, API writes — not as a
1361-
* cascade-only convention: an array field always reads as an array, so
1362-
* readers (generated code, formula/filter predicates) never need a null
1363-
* branch. Same ruling: `required` on a multi-value lookup means non-empty
1364-
* array (see `required` above).
1358+
* Multi-value empty representation (ruling A on #29343, record 6591577985,
1359+
* amending #9447, maintainer ruling 2026-08-18): a cleared OPTIONAL
1360+
* multi-value field — every type `isMultiValueField` answers true for:
1361+
* multiselect, checkboxes, tags, and select / lookup / user / file / image
1362+
* with `multiple: true` — is stored as `null` by the write door, the same as
1363+
* one never set, unique-covered or not: `[]` and `''` written to it store
1364+
* `null`. This binds the field's empty representation for EVERY writer —
1365+
* cascade repair (`set_null` member removal), form clears, API writes — not
1366+
* as a cascade-only convention. It reverses #9447's "an emptied multi-value
1367+
* lookup reads back as `[]`, never `null`" for optional columns: readers
1368+
* (generated code, formula/filter predicates) meet `null` for an empty set,
1369+
* and read `null` and `[]` alike as empty, since a row stored before the
1370+
* rule can still hold `[]`. The `$empty` table's `multi_value` row
1371+
* (`filter-empty-operator.ts`) is unchanged: `null` and `[]` both read as
1372+
* empty. #9447's other half stands: `required` on a multi-value field means
1373+
* non-empty list (see `required` above).
13651374
*
13661375
* Declarability: `multiple: true` outside the multi-capable types is refused
13671376
* at parse (maintainer ruling 2026-09-13), and on `radio` by the narrower
13681377
* 2026-08-22 ruling. The rulings and their dates live in these comments; the
13691378
* describe is form help in Studio and carries only the rule (#22093).
13701379
*/
1371-
multiple: z.boolean().default(false).describe('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. An emptied multi-value lookup reads back as `[]`, never `null` — the rule binds every writer (cascade repair, form clears, API writes), not just cascade repair.'),
1380+
multiple: z.boolean().default(false).describe('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.'),
13721381
// `true` = unique WITHIN the tenant on a tenant-scoped object (composite
13731382
// `(tenantField, field)` index); `'global'` = platform-wide single-column
13741383
// unique. See {@link UniqueScopeSchema} for the scope vocabulary (ADR-0120).

‎packages/spec/src/data/filter-empty-operator.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,8 @@ export const EMPTY_OPERATOR_ARMS: Readonly<Record<EmptyOperatorArm, EmptyOperato
8888
* The multi-value test runs first. The two sets are disjoint today (no
8989
* text-like type is multi-capable), so the order only decides a future
9090
* overlap, and it decides it by the stored SHAPE: a field whose value is a
91-
* list is emptied to `[]`.
91+
* list can hold `[]` (a cleared optional one stores `null`, but a row stored
92+
* before that rule can still hold `[]`).
9293
*/
9394
export function expandEmptyOperator(field: ValueShapeFieldDef): EmptyOperatorExpansion {
9495
if (isMultiValueField(field)) return EMPTY_OPERATOR_ARMS.multi_value;

0 commit comments

Comments
 (0)