[Decision] Should `@object-ui/types` ship a generated JSON Schema? — the contract an AI author can read before writing

[os-support-ai]

Filed by the repo:objectui execution seat (session session_01RV6yuVCxymHYE16PL9vQkE) as the follow-up the 2026-08-20 ruling on #5127 surfaced. Filed unassigned. ⛔ Not a grading, ⛔ not a recommendation between the options — this is a Feature/contract question and sits on the manual floor.

Where this came from

#5127 proposed minting a public $schema URL. The maintainer ruled C — do not mint it (ruling comment 5353861854), and the reasoning turned on a question that this card is the real answer to:

「为什么不用本地 node_modules」 · 「以后已经没有人用 vscode 了呀，代码都是 ai 写」

Under AI-first authoring, an agent does not want a URL an editor resolves. It wants two things:

1. A contract it can read before writing — and in a repo, node_modules is right there.
2. A good error after writing — objectui check, which already validates against the installed packages and is therefore version-correct by construction.

Item 2 exists. Item 1 does not, and that is this card.

Measured, on origin/main

@object-ui/types files	['dist', 'README.md', 'CHANGELOG.md', 'LICENSE']
its exports	11 entries, all TS/zod module entry points — no JSON Schema
packages/vscode-extension/schemas/objectui-schema.json	exists, 2723 bytes
what binds it	contributes.jsonValidation, by filename glob (*.objectui.json, *.oui.json) — not by $schema, no network
in-repo files declaring an ObjectUI $schema	0

⚠️ 2723 bytes is a stub, not a schema. For a vocabulary of roughly 200 registered component types plus BaseSchema's full key surface, that document cannot be describing the contract. Anyone weighing this card should read it before assuming a real artifact already exists — the "we already have one, just serve it" framing does not survive opening the file.

The question

Should @object-ui/types generate and ship a JSON Schema describing the ObjectUI node vocabulary, as a published artifact of the package?

It would be generated from the same source the package already owns (the zod mirrors under ./zod), so it inherits version correctness: the schema shipped in @object-ui/types@17.5.0 describes exactly what that version accepts. No skew, no serving obligation, no permanent identifier in users' files.

What it would buy, and what it would cost

Buys:

• The contract an agent reads before writing, at the version actually installed.
• It dissolves the $schema URL question that objectui check 把每个 JSON 文件的根 type 都当成组件键判定,于是在任何 Node 工程里都对 package.json 的 "type": "module" 报未知类型 #5127 hit. If a URL is ever wanted, the unpkg-pinned form this repo already uses for @changesets/config (https://unpkg.com/@changesets/config@4.0.0/schema.json) becomes available for free, version-pinned, with zero hosting.
• It gives packages/vscode-extension a real document to bind instead of the 2.7 KB stub.
• It may give objectui check 把每个 JSON 文件的根 type 都当成组件键判定,于是在任何 Node 工程里都对 package.json 的 "type": "module" 报未知类型 #5127's coverage debt a second route: today 258 real schema files (60.8%) leave the judgement surface because single-node leaves like {type: button, label: Send Email} carry no structural key by construction.

Costs — and these are why it is a decision, not a task:

• A generated artifact is a maintained artifact. It needs a generator, a gate that fails when it drifts from the zod source, and a place in the build. This repo has strong opinions about generated files (⛔ hand-editing them) and about gates whose green means "did not look".
• It publishes a second description of the contract. The zod mirrors are already one; a JSON Schema is a second. This repo has an open card family about exactly that shape ([finding] ComponentInput 有三份结构副本(types 两份 + core 一份)外加一个窄孪生 WidgetInput,而 #4580 的裁定说的是「re-export 而不是 restate」—— 副本之间今天已经有一处分歧 #4972, ComponentInput in three structural copies; finding(types): the zod BaseSchema mirror still declares visible/disabled as boolean and ariaLabel as string, after the TS declarations widened #4605, the zod mirror drifting from the TS declarations). Two descriptions that can disagree is the failure mode, and the mitigation — generate, never hand-write, and gate the drift — has to be part of whatever ships.
• Package size, if the schema is large and shipped to every consumer.

Not in scope here

⛔ This card does not re-open #5127's ruling. No public URL is minted by answering it either way.

Related

• objectui check 把每个 JSON 文件的根 type 都当成组件键判定,于是在任何 Node 工程里都对 package.json 的 "type": "module" 报未知类型 #5127 / PR5334 — the ruling that surfaced this; drops the $schema arm, keeps the structural arm and skip count
• [finding] ComponentInput 有三份结构副本(types 两份 + core 一份)外加一个窄孪生 WidgetInput,而 #4580 的裁定说的是「re-export 而不是 restate」—— 副本之间今天已经有一处分歧 #4972, finding(types): the zod BaseSchema mirror still declares visible/disabled as boolean and ariaLabel as string, after the TS declarations widened #4605 — the "two descriptions of one contract can disagree" family this would be joining
• .changeset/config.json — the in-repo precedent for an unpkg version-pinned $schema

---

Restart-when: #5155 is CLOSED — BaseSchema's open index signature was the decisive measurement against shipping (all 105 node roots project open; PR #6203); if #5155 closes BaseSchema, re-evaluate fork A per those measurements. Ruled 2026-08-25: B — do not ship now (recorded in the comments).

[os-zhuang]

<!-- os-decision-facets -->
Triage(决策箱勤务:入箱卡补标准四棱卡面块;定级 Feature,人工地板 —— 扩大公开面/新增发布物,座位不代裁)。四维分析:

① 项目长远合理性:契约应当有机器可读投影,这符合 contract-first;但 JSON Schema 是同一契约的第二份描述,本仓已有该形态的漂移事故家族(#4972 三份结构拷贝、#4605 zod 镜像漂移)。若 ship,「生成、⛔ 永不手写、drift 门禁红」必须是交付的一部分而非后补 —— 这是选项 A 的固定价格,不是可谈项。
② 实际业务拉动:主航道是 AI 写 app —— agent 写 metadata 前需要读得到的闭合契约,今天的替代品要么读 zod 源码(贵、间接),要么写完靠 objectui check 事后报错;vscode 侧现存的 2.7KB stub 覆盖不了 ~200 组件词表,等于没有。客户可感知差异:agent 首轮写对 vs 写错-报错-重写的迭代税。行业类比:@changesets/config 的 unpkg 版本 pin $schema 是本仓已在用的成熟范式,A 落地后该形态免费可得(不重开 #5127 的 URL 裁决)。
③ 防 AI 犯错:写前读到闭合枚举优于自由结构+事后拒绝 —— 方向正确;但两个反面:漂移的 schema 会让 AI「对着假契约写」,比没有更糟(⇒ drift gate 承重);且生成物只能忠实于源 —— BaseSchema 的 [key: string]: any(#5155)会原样投影成开放 schema,A 买不到 .strict() 没买的拒绝,两卡的先后关系值得在裁决时一并看。
④ 创业阶段不扩散:新常设生成器+门禁+构建位 = 永久维护义务;但服务的是主航道而非投机面。可最小化形态:仅 build 时生成、不承诺 URL、不进运行时。

选项:A ship 生成的 JSON Schema(含 drift 门禁,发布进 @object-ui/types)/ B 不 ship —— 维持 zod 源 + objectui check 两件套 / C 只为 packages/vscode-extension 生成完整 schema,不进包发布面(中间态,维护义务较小,但 agent 面收益归零)。

一行强制置信缺口(本分析看不见什么):zod→JSON Schema 转换在本仓 zod 形态上的保真度未测(lazySchema/refine/effects 常不可转或转成 {},若大面积失真则 A 的收益名不副实);生成物体积未测;#5127 那 60.8% 无结构键的文件是否真会因此获得判定面,是推断不是测量。若维护者倾向 A,建议按「带前提的裁决」形态:先派一张测量卡(转换保真度 + 体积),前提不成立报 fork。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling recorded (2026-08-22, decision-inbox digest with the skills seat, session_01ApyDuQY2fkunMCqXiqvBhR)

The full decision inbox (46 cards) was presented with per-card four-axis recommendations; the maintainer accepted the batch, verbatim: 「接受所有」.

Ruled: A measurement card first. This card's first step is the measurement flagged as the mandatory confidence gap: the fidelity of zod→JSON Schema conversion on this repo's actual zod shapes (lazySchema/refine/effects, which often convert poorly or to {}), the size of the generated artifact, and whether #5127's 60.8% structure-key-less files would actually gain a judgement surface. The fork between A (ship a generated JSON Schema with a drift gate in @object-ui/types), B (do not ship; keep zod source + objectui check), and C (vscode-extension-only schema) is deliberately NOT decided now — it is decided by the measured result. If the measurement falsifies the premise, report the fork rather than proceeding.

State: needs-user-decision removed → pm:queue (ready for dispatch).

---

Generated by Claude Code

[claude]

Triage (daily round, session session_01Kktexqp6uVuFMztvvTMf3V, 2026-08-24): domain:ui added (types package measurement; pm:queue already present). The 2026-08-22 ruling stands: measurement card first — the dispatch is the fidelity measurement, not the generator.

---

Generated by Claude Code