Skip to content

Commit 2b566c7

Browse files
committed
docs: an object extension's fieldPatches on the extensions page; regenerated object reference
Claude-Session: https://claude.ai/code/session_01FEkQ5nSMgkteiemkoN31vf Co-authored-by: Claude <noreply@anthropic.com>
1 parent d108bd0 commit 2b566c7

2 files changed

Lines changed: 50 additions & 4 deletions

File tree

‎content/docs/data-modeling/object-extensions.mdx‎

Lines changed: 49 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Object extensions — extend without forking
33
navTitle: Object Extensions
4-
description: Add fields, validations and indexes to an object another package owns, without forking it — declaration, merge order, and what an extension may not contribute.
4+
description: Add fields, validations and indexes to an object another package owns, or relabel its fields, without forking it — declaration, merge order, and what an extension may not contribute.
55
---
66

77
Every object has exactly **one owning package**. That package defines the table, the
@@ -63,6 +63,7 @@ check that spelling first.
6363
| Key | Merge behaviour |
6464
|:---|:---|
6565
| `fields` | **Additive.** Merged into the target's field map. A name the target already has is **replaced**, not merged. |
66+
| `fieldPatches` | **Applied, field by field.** Changes the *display* of one of the target's own fields without replacing it — [below](#relabelling-a-vendor-field). |
6667
| `validations` | **Concatenated.** Your rules run alongside the owner's; neither replaces the other. |
6768
| `indexes` | **Concatenated**, same as validations. |
6869
| `label` | Replaces the target's label — with one exception, [below](#extensions-and-tenant-customization). |
@@ -76,7 +77,7 @@ Added fields are ordinary fields, so everything on the
7677

7778
### What an extension may **not** contribute
7879

79-
The merge carries the seven keys above and nothing else. These four are not
80+
The merge carries the eight keys above and nothing else. These four are not
8081
"unsupported yet" — there is no slot for them to arrive through, and the schema rejects
8182
each one by name with the alternative to use instead:
8283

@@ -92,6 +93,50 @@ fails at authoring time with a prescription rather than being dropped in silence
9293

9394
---
9495

96+
## Relabelling a vendor field
97+
98+
Replacing a field through `fields` takes it over whole: its type, its options and its
99+
rules become yours, and the owner's next version no longer reaches it. To change only
100+
what a person *reads* — "Industry" shown as "Sector", a better help text — patch the
101+
field instead:
102+
103+
{/* os:check */}
104+
```typescript
105+
import { defineObjectExtension } from '@objectstack/spec/data';
106+
107+
export const AccountWordingExtension = defineObjectExtension({
108+
extend: 'crm_account',
109+
fieldPatches: {
110+
industry: {
111+
label: 'Sector',
112+
inlineHelpText: 'The market the account sells into.',
113+
options: { tech: { label: 'Technology' } }, // addressed by the stored value
114+
},
115+
},
116+
});
117+
```
118+
119+
A patch sets `label`, `description`, `inlineHelpText` and `placeholder` on the field, and
120+
the `label` of an option it addresses by its stored `value` — the display whitelist
121+
(`BASE_FIELD_DISPLAY_WHITELIST`), and nothing else. The field's type, requiredness,
122+
default, formula and which options exist stay the owner's, so the owner's upgrades keep
123+
applying and stored values never change; any other key is refused by name with that
124+
reason.
125+
126+
- **Every read serves it.** The patch is applied in the same merge as the other keys,
127+
after the additive ones — so it can also reach a field a lower-priority extension
128+
added — and the list, the by-name read and the layered view agree. Uninstalling the
129+
extension serves the owner's text again.
130+
- **Conflicts resolve like `label`.** Two extensions patching the same key: the higher
131+
`priority` wins. A tenant who has edited that text keeps their own, [below](#extensions-and-tenant-customization).
132+
- **A patch must name something real.** A field the target does not have, or an option
133+
value its field does not have, is refused when the package installs and by
134+
`os validate` when the target is in the same stack. A field whose options come from a
135+
shared picklist has no option labels of its own to patch. At boot, an unmatched patch
136+
is not applied and is named once in the log; the boot carries on.
137+
138+
---
139+
95140
## Naming the fields you add
96141

97142
Field names in an extension are **not** namespace-prefixed by the platform. The
@@ -140,7 +185,8 @@ survive a customized object rather than being dropped by it.
140185
One deliberate asymmetry, ruled 2026-08-13: an extension's `label`, `pluralLabel` and
141186
`description` apply only while the base still carries the **packaged owner's** value.
142187
Once a tenant has renamed the object, the extension's packaged default yields and the
143-
tenant's name stands. Fields, validations and indexes are unaffected — they merge
188+
tenant's name stands. A `fieldPatches` key yields the same way, one field (and option)
189+
at a time: a field label the tenant edited keeps the tenant's text. Fields, validations and indexes are unaffected — they merge
144190
either way. There is no escape hatch: a package cannot relabel an object a tenant has
145191
deliberately renamed.
146192
</Callout>

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -576,7 +576,7 @@ const result = ApiMethod.parse(data);
576576
| :--- | :--- | :--- | :--- |
577577
| **extend** | `string` | ✅ | Target object name (FQN) to extend |
578578
| **fields** | `Record<string, { name?: string; label?: string; type: Enum<'text' \| 'textarea' \| 'email' \| 'url' \| 'phone' \| 'password' \| 'secret' \| …>; description?: string; … }>` | optional | Fields to add/override |
579-
| **fieldPatches** | `Record<string, { label?: string; description?: string; inlineHelpText?: string; placeholder?: string; … }>` | optional | [EXPERIMENTAL — not enforced] Display patches of the target object's own fields, keyed by field name: change a vendor field's display properties (BASE_FIELD_DISPLAY_WHITELIST: label, description, help text, placeholder, option labels) without taking the field over, so its type, values and rules stay the vendor's and its upgrades still apply (ADR-0146 D10). Nothing applies a patch yet: the registry merge that does is rollout card N-23d, and until it lands the engine drops this slot at registration. Example: `fieldPatches: { industry: { label: 'Sector', inlineHelpText: 'The market the account sells into', options: { tech: { label: 'Technology' } } } }`. |
579+
| **fieldPatches** | `Record<string, { label?: string; description?: string; inlineHelpText?: string; placeholder?: string; … }>` | optional | Display patches of the target object's own fields, keyed by field name: change a vendor field's display properties (BASE_FIELD_DISPLAY_WHITELIST: label, description, help text, placeholder, option labels) without taking the field over, so its type, values and rules stay the vendor's and its upgrades still apply (ADR-0146 D10). Applied by the registry merge (`mergeObjectDefinitions`) after the additive merges, on every object read: a tenant's own text keeps winning, and between two extensions the higher `priority` wins. A patch naming a field or option value the target does not have is refused at install and by `os validate`. Example: `fieldPatches: { industry: { label: 'Sector', inlineHelpText: 'The market the account sells into', options: { tech: { label: 'Technology' } } } }`. |
580580
| **label** | `string` | optional | Override label for the extended object |
581581
| **pluralLabel** | `string` | optional | Override plural label for the extended object |
582582
| **description** | `string` | optional | Override description for the extended object |

0 commit comments

Comments
 (0)