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 27f8315
Browse filesBrowse the repository at this point in the historyBrowse files
docs(spec): a field's externalId description stops promising upserts
The flag is graded dead: no upsert, import or seed reads it. The schema
description, the generated reference pages and three hand-written field
tables now say so and name the two keys that do match records.
Co-authored-by: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L9qibvE77Ed7MKdzPxJTQQ
Copy file name to clipboardExpand all lines: .changeset/25753-field-external-id-dead.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,10 +4,10 @@
4
4
5
5
fix(spec): `os lint` tells an author that a field's `externalId: true` does nothing
6
6
7
-
Clause-②: no (a liveness-ledger re-grade: no schema, accept set, served body or error code moves; only the advisory `liveness-dead-property` warning on an authored `externalId: true` starts)
7
+
Clause-②: no (a liveness-ledger re-grade: no schema, accept set, served body or error code moves; only the advisory `liveness-dead-property` warning on an authored `externalId: true` starts, and the flag's description is reworded)
8
8
Metadata-protocol: none
9
9
10
-
The shipped liveness ledger (`liveness/field.json`) graded a field's `externalId` flag `live` on the strength of one renderer module that was deleted for having no importers. Re-measured across `packages/**` and `ui/**`, nothing reads the flag: the Studio field inspector edits it and a metadata summary copies it, and no upsert matches on it. The row is now `dead`, so `os lint` warns on a field that sets `externalId: true` (the default `false` is not warned).
10
+
The shipped liveness ledger (`liveness/field.json`) graded a field's `externalId` flag `live` on the strength of one renderer module that was deleted for having no importers. Re-measured across `packages/**` and `ui/**`, nothing reads the flag: the Studio field inspector edits it and a metadata summary copies it, and no upsert matches on it. The row is now `dead`, so `os lint` warns on a field that sets `externalId: true` (the default `false` is not warned). The flag's schema description, and the reference pages generated from it, no longer say it drives upserts.
11
11
12
12
-**What to do.** Remove the flag. To match seed records on a field, name the field in the seed dataset's `externalId` (`name` when it is left out). For an import, name it in the mapping's `upsertKey`.
13
13
-**Unchanged.** Parsing (the key is still accepted, default `false`), seed loading, imports and every upsert.
| `readonly` | `boolean` | `false` | Server contract — non-system writes to this field are stripped on **both** INSERT and UPDATE (the value falls back to `defaultValue`), not just hidden in the UI (#2948 / #3043) |
| `externalId` | `boolean` | `false` | Not read: nothing matches on it. A seed dataset names its match field in its own `externalId`, an import in its mapping's `upsertKey` |
696
696
| `defaultValue` | `any` | — | Default value for new records |
Copy file name to clipboardExpand all lines: content/docs/data-modeling/fields.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -369,7 +369,7 @@ These properties are available on all field types:
369
369
| Property | Type | Default | Description |
370
370
| :--- | :--- | :--- | :--- |
371
371
|`searchable`|`boolean`|`false`| Include in full-text search |
372
-
|`externalId`|`boolean`|`false`|Mark as external system identifier|
372
+
|`externalId`|`boolean`|`false`|Not read: nothing matches on it. A seed dataset names its match field in its own `externalId`, an import in its mapping's `upsertKey`|
373
373
374
374
Database indexes are declared at the object level in the object's `indexes[]` array — there is no per-field `index` flag. See [Indexing](/docs/data-modeling/indexing).
Copy file name to clipboardExpand all lines: content/docs/data-modeling/validation-rules.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,7 @@ These properties apply to **all** field types and are validated by the base `Fie
28
28
|`hidden`|`boolean`|`false`| Excluded from default UI rendering |
29
29
|`readonly`|`boolean`|`false`| Blocks user edits in UI forms; server-enforced on **both create and update** — a non-system write to the field is silently dropped from the payload (system-context writes such as import/seed/migration are exempt) |
30
30
|`sortable`|`boolean`|`true`| Whether field appears in list view sort options |
31
-
|`externalId`|`boolean`|`false`|Marks field as external ID for upsert operations|
31
+
|`externalId`|`boolean`|`false`|Not read: nothing matches on it. A seed dataset names its match field in its own `externalId`, an import in its mapping's `upsertKey`|
32
32
|`trackHistory`|`boolean`| — | Render this field's value changes as entries on the record activity timeline |
33
33
|`visibleWhen`|`string \| Expression`| — | CEL predicate; field is shown only when `TRUE`|
34
34
|`readonlyWhen`|`string \| Expression`| — | CEL predicate; field is read-only when `TRUE`|
Copy file name to clipboardExpand all lines: content/docs/references/data/field.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -124,7 +124,7 @@ const result = CurrencyConfigSchema.parse(data);
124
124
|**inlineHelpText**|`string`| optional | Help text displayed below the field in forms |
125
125
|**placeholder**|`string`| optional | Placeholder 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). |
126
126
|**autonumberFormat**|`string`| optional (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. |
127
-
|**externalId**|`boolean`| optional (default: `false`) |Is external ID for upsert operations|
127
+
|**externalId**|`boolean`| optional (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`.|
Copy file name to clipboardExpand all lines: content/docs/references/data/object.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -292,7 +292,7 @@ const result = ApiMethod.parse(data);
292
292
|**inlineHelpText**|`string`| optional | Help text displayed below the field in forms |
293
293
|**placeholder**|`string`| optional | Placeholder 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). |
294
294
|**autonumberFormat**|`string`| optional (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. |
295
-
|**externalId**|`boolean`| optional (default: `false`) |Is external ID for upsert operations|
295
+
|**externalId**|`boolean`| optional (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`.|
|**_lockReason**|`string`| optional | Human-readable reason shown when a write is refused by _lock. |
298
298
|**_lockSource**|`Enum<'artifact' \| 'package' \| 'env-forced'>`| optional | Layer that set _lock (artifact \| package \| env-forced). |
@@ -664,7 +664,7 @@ const result = ApiMethod.parse(data);
664
664
|**inlineHelpText**|`string`| optional | Help text displayed below the field in forms |
665
665
|**placeholder**|`string`| optional | Placeholder 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). |
666
666
|**autonumberFormat**|`string`| optional (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. |
667
-
|**externalId**|`boolean`| optional (default: `false`) |Is external ID for upsert operations|
667
+
|**externalId**|`boolean`| optional (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`.|
Copy file name to clipboardExpand all lines: content/docs/references/system/migration.mdx
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -125,7 +125,7 @@ Add a new field to an existing object
125
125
|**inlineHelpText**|`string`| optional | Help text displayed below the field in forms |
126
126
|**placeholder**|`string`| optional | Placeholder 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). |
127
127
|**autonumberFormat**|`string`| optional (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. |
128
-
|**externalId**|`boolean`| optional (default: `false`) |Is external ID for upsert operations|
128
+
|**externalId**|`boolean`| optional (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`.|
|**_lockReason**|`string`| optional | Human-readable reason shown when a write is refused by _lock. |
131
131
|**_lockSource**|`Enum<'artifact' \| 'package' \| 'env-forced'>`| optional | Layer that set _lock (artifact \| package \| env-forced). |
@@ -556,7 +556,7 @@ Add a new field to an existing object
556
556
|**inlineHelpText**|`string`| optional | Help text displayed below the field in forms |
557
557
|**placeholder**|`string`| optional | Placeholder 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). |
558
558
|**autonumberFormat**|`string`| optional (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. |
559
-
|**externalId**|`boolean`| optional (default: `false`) |Is external ID for upsert operations|
559
+
|**externalId**|`boolean`| optional (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`.|
// `index` (field-level bool) removed in the 16.x line (#2377, ADR-0049): the
2322
2322
// driver builds indexes from the object's `indexes[]` array; a field-level
2323
2323
// `index: true` created no index. Declare the index in object `indexes[]`.
2324
-
externalId: z.boolean().default(false).describe('Is external ID for upsert operations'),
2324
+
externalId: z.boolean().default(false).describe('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`.'),
2325
2325
2326
2326
// ADR-0010 — runtime protection envelope (internal — set by the loader).
2327
2327
// `field` is a registered metadata type, so `MetadataPlugin`'s loader stamps
0 commit comments