Skip to content

Commit 27f8315

Browse files
committed
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
1 parent 5d9b4d7 commit 27f8315

8 files changed

Lines changed: 11 additions & 11 deletions

File tree

‎.changeset/25753-field-external-id-dead.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@
44

55
fix(spec): `os lint` tells an author that a field's `externalId: true` does nothing
66

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)
88
Metadata-protocol: none
99

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.
1111

1212
- **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`.
1313
- **Unchanged.** Parsing (the key is still accepted, default `false`), seed loading, imports and every upsert.

‎content/docs/data-modeling/field-types.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -692,7 +692,7 @@ These properties are available on **all** field types:
692692
| `sortable` | `boolean` | `true` | Allow sorting by this field |
693693
| `hidden` | `boolean` | `false` | Hide from default views |
694694
| `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) |
695-
| `externalId` | `boolean` | `false` | External system identifier |
695+
| `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` |
696696
| `defaultValue` | `any` | — | Default value for new records |
697697
| `group` | `string` | — | Field grouping / section |
698698
| `inlineHelpText` | `string` | — | Inline help tooltip |

‎content/docs/data-modeling/fields.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -369,7 +369,7 @@ These properties are available on all field types:
369369
| Property | Type | Default | Description |
370370
| :--- | :--- | :--- | :--- |
371371
| `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` |
373373

374374
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).
375375

‎content/docs/data-modeling/validation-rules.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ These properties apply to **all** field types and are validated by the base `Fie
2828
| `hidden` | `boolean` | `false` | Excluded from default UI rendering |
2929
| `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) |
3030
| `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` |
3232
| `trackHistory` | `boolean` | — | Render this field's value changes as entries on the record activity timeline |
3333
| `visibleWhen` | `string \| Expression` | — | CEL predicate; field is shown only when `TRUE` |
3434
| `readonlyWhen` | `string \| Expression` | — | CEL predicate; field is read-only when `TRUE` |

‎content/docs/references/data/field.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ const result = CurrencyConfigSchema.parse(data);
124124
| **inlineHelpText** | `string` | optional | Help text displayed below the field in forms |
125125
| **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). |
126126
| **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`. |
128128
| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
129129
| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
130130
| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |

‎content/docs/references/data/object.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -292,7 +292,7 @@ const result = ApiMethod.parse(data);
292292
| **inlineHelpText** | `string` | optional | Help text displayed below the field in forms |
293293
| **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). |
294294
| **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`. |
296296
| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
297297
| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
298298
| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
@@ -664,7 +664,7 @@ const result = ApiMethod.parse(data);
664664
| **inlineHelpText** | `string` | optional | Help text displayed below the field in forms |
665665
| **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). |
666666
| **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`. |
668668
| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
669669
| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
670670
| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |

‎content/docs/references/system/migration.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ Add a new field to an existing object
125125
| **inlineHelpText** | `string` | optional | Help text displayed below the field in forms |
126126
| **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). |
127127
| **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`. |
129129
| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
130130
| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
131131
| **_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
556556
| **inlineHelpText** | `string` | optional | Help text displayed below the field in forms |
557557
| **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). |
558558
| **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`. |
560560
| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
561561
| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
562562
| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2321,7 +2321,7 @@ export const FieldSchema = lazySchema(() => {
23212321
// `index` (field-level bool) removed in the 16.x line (#2377, ADR-0049): the
23222322
// driver builds indexes from the object's `indexes[]` array; a field-level
23232323
// `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`.'),
23252325

23262326
// ADR-0010 — runtime protection envelope (internal — set by the loader).
23272327
// `field` is a registered metadata type, so `MetadataPlugin`'s loader stamps

0 commit comments

Comments
 (0)