You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit a566c0c
Browse filesBrowse the repository at this point in the historyBrowse files
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>
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.
* On a multi-value lookup (`multiple: true`), `required` means NON-EMPTY
1315
1315
* 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).
1321
1322
*/
1322
1323
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.'),
* 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).
1365
1374
*
1366
1375
* Declarability: `multiple: true` outside the multi-capable types is refused
1367
1376
* at parse (maintainer ruling 2026-09-13), and on `radio` by the narrower
1368
1377
* 2026-08-22 ruling. The rulings and their dates live in these comments; the
1369
1378
* describe is form help in Studio and carries only the rule (#22093).
1370
1379
*/
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.'),
1372
1381
// `true` = unique WITHIN the tenant on a tenant-scoped object (composite
0 commit comments