Skip to content

Commit 2a26536

Browse files
claude[bot]claude
andauthored
docs(objectui): widen check-docs-section-name to singular section: and json fences (#14558)
- scripts/check-docs-section-name.mjs: new selector for a singular YAML section: mapping (any nesting) and a new JSON-family arm (json/jsonc/json5) that bracket-matches sections: [ ... ] arrays the same way the TS arm does. Both are shape-based, not marker-based, per the #13880 triage ruling. - content/docs/protocol/objectui/concept.mdx: the Layer 2 customizations: overlay-diff fence taught a shape packages/spec never declared (the retired paper metadata-customization protocol, ADR-0126 #13135) and is replaced with a Callout citing that; the Final Merged Layout json fence and the earlier Server Response json fence now carry name: on their sections. Fixes #13880 Co-authored-by: Claude <noreply@anthropic.com>
1 parent 3bca6a4 commit 2a26536

2 files changed

Lines changed: 469 additions & 94 deletions

File tree

‎content/docs/protocol/objectui/concept.mdx‎

Lines changed: 32 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -305,6 +305,7 @@ Authorization: Bearer <token>
305305
"layout": {
306306
"sections": [
307307
{
308+
"name": "contact_information",
308309
"label": "Contact Information",
309310
"columns": 2,
310311
"fields": [
@@ -389,8 +390,7 @@ ObjectUI merges **3 layers** of configuration to produce the final layout:
389390
↓ Merge
390391
┌─────────────────────────────────────────────────────┐
391392
│ Layer 2: Admin Configuration │
392-
│ - Custom sections: Added "Billing Info" section │
393-
│ - Field overrides: Made 'phone' required │
393+
│ - Org overlay: a full FormView write, not a diff │
394394
│ - Branding: Logo, colors, theme │
395395
└────────────────┬────────────────────────────────────┘
396396
↓ Merge
@@ -415,17 +415,34 @@ fields:
415415
```
416416
417417
**Layer 2: Admin Customization (Acme Corp tenant)**
418-
```yaml
419-
customizations:
420-
- field: phone
421-
required: true # Override: Make phone required
422-
- field: vip_status
423-
type: boolean
424-
label: VIP Customer # Add custom field
425-
- section:
426-
label: Billing Info
427-
fields: [payment_terms, credit_limit]
428-
```
418+
419+
<Callout type="warn">
420+
Earlier revisions of this page taught a `customizations:` overlay-diff list
421+
here — `{ field: ... }` and `{ section: ... }` entries meant to patch Layer
422+
1's fields and add a section. **That list is not a declared shape.** The
423+
only `customizations` key `packages/spec` declares at all is
424+
`tenant.zod.ts`'s free-form `z.record(z.string(), z.unknown())`; there is no
425+
`{ field | section }` overlay schema for it to validate against, and
426+
`FormViewSchema` is `.strict()` — authoring this fence as a real form view
427+
would be refused by name.
428+
429+
It is not merely undeclared: the three-layer *merge engine* this example
430+
narrates is the paper `metadata-customization` protocol retired in
431+
`@objectstack/spec` 17 (#13135, ADR-0049 enforce-or-remove). Its
432+
`customizationPolicies` and `mergeStrategy` keys are tombstoned rather than
433+
deleted (`MetadataPluginConfig`) — read by nothing, because no 3-way merge
434+
engine ever ran and package upgrades never merge customizations
435+
(ADR-0126 §6 wall 3: an upgrade rewrites the packaged BASE; a tenant's
436+
choices live separately and are never merged into it).
437+
438+
What Acme Corp actually customizes at runtime is a real, declared shape: a
439+
per-org **overlay write on the `view` metadata type**
440+
(`allowOrgOverride: true` on its `DEFAULT_METADATA_TYPE_REGISTRY` entry,
441+
ADR-0005) — the org's own `FormView` document, authored with the same shape
442+
Layer 1 and the Server Response above already use, not a diff against the
443+
base. The merged layout below reflects only what Layers 1 and 3 (both real,
444+
declared shapes) actually produce.
445+
</Callout>
429446

430447
**Layer 3: User Preferences (John Doe)**
431448
```json
@@ -441,18 +458,12 @@ customizations:
441458
{
442459
"sections": [
443460
{
461+
"name": "contact_information",
444462
"label": "Contact Information",
445463
"fields": [
446464
{ "name": "name", "required": true, "width": 250 },
447465
{ "name": "email", "required": true, "width": 200 },
448-
{ "name": "phone", "required": true } // ← Admin override
449-
]
450-
},
451-
{
452-
"label": "Billing Info", // ← Admin customization
453-
"fields": [
454-
{ "name": "payment_terms" },
455-
{ "name": "credit_limit" }
466+
{ "name": "phone", "required": false }
456467
]
457468
}
458469
],

0 commit comments

Comments
 (0)