decision(spec): which schema does an SDUI dashboard COMPONENT node validate against? DashboardSchema rejects every objectui catalog example on three independent axes

[yinlianghui]

Decision card routed from objectui#4600 (PM session session_017Qqyix2QcnpUC9XeYVDzx3), on the contract-first pattern of #7496/#7917. Full measurement: objectui#4600, comment 5287946890 (measured at objectui f69127fcc, @objectstack/spec@17.0.0-rc.6).

The question

objectui ships a schema catalog of SDUI component JSON (type: 'dashboard' nodes rendered by SchemaRenderer), published in the docs gallery and declared an AI RAG/few-shot corpus. All 9 plugin-dashboard entries are REJECTED by the spec's DashboardSchema — but on three axes with different meanings, and no existing ruling says which schema such a node is supposed to satisfy:

• Class A — metadata identity: every entry lacks name/label. DashboardSchema models a stored platform metadata DOCUMENT; an SDUI component node has no metadata identity by construction.
• Class B — SDUI envelope: type: 'dashboard' (all 9) and title (6) are unrecognized_keys to the spec — but type is what makes it an SDUI node at all.
• Class C2 — metric-card: 3 entries / 11 widgets use objectui's metric-card (static presentational value/icon/trend), which is not in the spec's 20-value widget enum and has no dataset behind a hard-coded string. These render perfectly today; they are only spec-invalid.

(Class C1 — the retired inline-analytics shape — is NOT part of this question; objectui is fixing those examples to live surfaces under its own card.)

The options, as measured

1. An SDUI dashboard node is validated by objectui's own DashboardWidgetSchema/component schema, not the spec's DashboardSchema — the spec document schema governs stored metadata only. Then the catalog gate objectui wants is against the component schema, and classes A/B are non-issues by definition. Cost: the corpus never demonstrates the platform-metadata form.
2. The spec grows an explicit component/embedded projection of DashboardSchema (identity-optional, envelope-aware) that SDUI nodes validate against. Cost: a new spec surface with its own maintenance.
3. The catalog migrates to genuine metadata documents (add identity, drop the envelope) and the SDUI corpus is regenerated from them. Cost: measured in objectui#4600 — it inverts what the examples are for, and metric-card still has no home.
4. metric-card: joins the spec's widget enum (with a static-value story) / stays an objectui extension explicitly allowed by whichever schema wins above.

objectui's downstream work (gallery truth, the narrow GlobalFilterSchema gate from #4356) proceeds either way; a full DashboardSchema catalog gate stays impossible until this is ruled.

---

Generated by Claude Code

[hotlong]

Triage: four-prism block (required kit for the decision inbox; the routed card carried the measurement but not the block). Native type Feature (options 2 and 4-join-enum expand the spec's public face; that mechanically keeps this on the human floor — no auto-adjudication, correctly in the inbox).

• Platform long-term coherence: option 1 keeps one schema = one meaning — DashboardSchema models the stored metadata document; an SDUI component node is objectui's rendering contract. Option 2 mints a second, identity-optional projection of the same schema that the spec then maintains forever. → 1
• Measured business pull: all 9 catalog entries render fine today; no user is broken. The only pull is objectui's catalog gate, which option 1 already unblocks (gate against the component schema). Zero measured pull for new spec surface. → 1
• AI-agent error-resistance: the catalog is a declared RAG/few-shot corpus, so it must be validatable by something closed. Option 1 gives an enforceable gate now on objectui's side, while the spec's strict document schema keeps rejecting component JSON pasted into metadata loudly — the protection that matters. Caveat on option 4: metric-card should become a member of objectui's own closed widget enum, not an open "extension allowed" escape hatch. → 1
• Startup scope discipline: options 2 and 4-join-spec-enum are declare-and-maintain surface for zero pull; option 3 inverts what the examples are for. → 1

Recommendation: option 1 — an SDUI dashboard COMPONENT node validates against objectui's component schema; the spec's DashboardSchema governs stored metadata documents only; metric-card joins objectui's closed component enum (option 4's objectui arm, made closed). All four prisms point the same way, but the class (which contract governs a published surface) is a protocol-shape ruling — maintainer's call.

Downstream dependency flag (per standing instruction ④): objectui#4600's catalog-gate work is soft-blocked on this ruling.

---

Generated by Claude Code

[hotlong]

Maintainer ruling (2026-08-14, verbatim: 「同意你的建议」, approving item 5 of the eight-item decision-box list: 「#8593:选项 1 ＋ metric-card 进 objectui 封闭枚举?」): option 1 — an SDUI dashboard COMPONENT node validates against objectui's own component schema (DashboardWidgetSchema family); the spec's DashboardSchema governs stored dashboard metadata documents only and grows no component projection. metric-card joins objectui's own closed component enum as an explicitly-allowed objectui extension, not the spec widget enum. The decision is this card's whole deliverable — spec changes: none — so the card closes with the ruling; implementation (catalog gate + enum) proceeds in objectstack-ai/objectui#4600, which was soft-blocked on exactly this and is now unblocked.

---

Generated by Claude Code