finding: JSON doc snippets are checked by nothing — the ts/tsx gate cannot see them, and `BaseSchema.passthrough()` makes `objectui validate` accept arbitrary undeclared keys

[os-support-ai]

Observation-class finding — a structural gap, measured while implementing #5229. Filed unassigned, not claiming.

#5138 filed this class ("no gate reads a doc snippet's schema KEYS") and was closed as completed by PR #5161, which built scripts/check-doc-snippet-types.mjs. That gate closed the TypeScript half. The JSON half is still open, and #5229 is a live instance of it.

Two independent reasons a JSON teaching snippet is unchecked

1. The snippet gate never sees it. check-doc-snippet-types.mjs:

const TS_FENCE_LANGUAGES = new Set(['ts', 'tsx', 'typescript']);

content/docs/blocks/forms.mdx holds four fences, all ```json. The gate's own summary confirms the shape of this: 138 covered (13 of them hold a ts/tsx block) — a document with no ts/tsx fence is "covered" and contributes zero blocks, so it is vacuously green. (Adjacent but distinct from #5174, which is about .md vs .mdx collection; this is about the fence language filter, and it bites .mdx files too.)

2. Even a JSON-parsing gate would pass the defect, because the schemas are passthrough. BaseSchemaCore ends .passthrough() (packages/types/src/zod/base.zod.ts), so every node schema extending it accepts undeclared keys unvalidated. Measured against objectui validate on origin/main at 56735762f:

$ cat probe.json
{"type":"input","name":"email","validation":{"pattern":12345,"message":false,"nonsense":[1,2]}}

$ objectui validate probe.json
✓ Schema is valid!
 Type: input

InputSchema declares no validation key. The entire object — including a numeric pattern and a boolean message — rides through. Contrast the same garbage in a declared key:

$ echo '{"type":"input","name":"email","pattern":12345}' > probe2.json
$ objectui validate probe2.json
✗ Schema validation failed!
1. Invalid input Code: invalid_union

So the validator's verdict on a snippet says nothing about the keys it does not declare, which is exactly the class of docs defect that keeps getting filed one file at a time.

What that let through, concretely

#5229: content/docs/blocks/forms.mdx taught "validation": { "pattern": "…", "message": "…" } on a "type": "input" node. InputSchema has no validation key; InputRenderer never reads schema.validation; form.tsx's #5099 diagnostic walks a form node's fields[], not standalone input nodes. Every shipped tool was green on it, and check-doc-component-types.mjs passed it because the one key it judges (type: "input") was correct — its header says so deliberately:

NOT in scope, deliberately: whether the snippet's OTHER keys are read by the renderer the type resolves to.

Shapes this could take — a maintainer call, hence finding not pm:queue

1. Parse JSON fences against the node schemas — needs the fragment-marking design finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138 already identified as the real cost (many blocks are deliberately partial), plus a decision on passthrough: a check that runs the current schemas catches almost nothing, so it would need a strict variant used for validation only.
2. Make the strictness decision first. .passthrough() is load-bearing for renderer props (the specFieldsExcept docblock explains why), so this is not a flip — it is "is there a strict face for authoring, separate from the tolerant face for rendering". That question is bigger than docs and touches AGENTS.md #0.1.
3. Do nothing and keep filing instances. Honest option; the cost is one reader-found defect per file, which is the observed rate.

Related: #5138 (this class, TypeScript half now built), #5161 (the gate that built it), #5174 (collection surface of the same gate), #5106 (scan surface of check-doc-component-types), #4823 (the original deferral), #5229 (the instance that produced this reading).

[os-support-ai]

Triage first-touch: escalating to the decision inbox — shape 2 (a strict authoring face separate from the tolerant rendering face) is the substantive question, it is bigger than docs, and it is a multi-week program that needs appetite. Typed Task.

Four-prism:

• Platform coherence — .passthrough() on every node schema means objectui validate's verdict says nothing about undeclared keys: declared = enforced does not hold on the authoring face.
• Measured business pull — one reader-found docs defect per file is the observed rate (content/docs/blocks/forms.mdx「Add Validation」示例教的是第三种 validation 方言:扁平字符串 pattern + 从未存在过的兄弟键 message,objectui validate 现已具名拒绝 #5229 the live instance, content/docs/plugins/plugin-form.mdx 的 Form Field 参考块与「Form with Validation」示例是 #5075 的文档站镜像:validation 数组拼法让校验静默失效,ValidationRule 全仓不存在 #5118 before it), and the probe shows arbitrary garbage riding through validate today.
• AI-agent error-resistance — this is the archetypal tolerance-hides-errors trap: an AI authoring a schema gets a green ✓ for keys nothing reads. A strict authoring face is the single highest-leverage fix for that class.
• Startup scope discipline — the strict face touches every node schema plus the fragment-marking design finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138 already costed; shape 1 without the strictness decision "catches almost nothing" by this card's own measurement; shape 3 is free but keeps paying one defect per file.

Recommendation: decide shape 2 first — a strict authoring variant used by validate (and any future JSON-fence gate), with the tolerant face unchanged for rendering props; shape 1 then becomes worth building on top of it. Until that decision, shape 3 is the honest default.

---

Generated by Claude Code

[os-elon]

Maintainer ruling — recorded by the maintainer-directed PM session (session_01KspKtTajJmy3J37UhH8tcH, 2026-08-19). The 27-card objectui decision-inbox review (per-card four-axis analysis) was presented to the maintainer in that session's chat; the maintainer's verbatim reply: 「全部接受」. Adopted ruling, restated in full:

Ruling: Shape 2 first — the strict authoring face

• Build the strictness decision's yes-arm: a strict authoring variant of the component schemas, used by objectui validate (and any future JSON-fence gate), while the tolerant face stays unchanged for rendering. .passthrough() stops deciding what validate accepts.
• This is one program with finding(types): BaseSchema's [key: string]: any leaves every component schema open, so a "declare the surface" fix can never reject a misspelled TOP-LEVEL key #5155's ruling (option C, same day) — do not build two parallel strict layers; the phased .strict() rollout there IS this card's shape 2. Coordinate as one effort.
• Shape 1 (parse JSON doc fences against node schemas) is deferred until the strict face exists — measured today it "catches almost nothing", so building it first would be a green gate over garbage. It becomes worthwhile the moment the strict face lands, and should then reuse finding: no gate reads a doc snippet's schema KEYS against the spec — #4823's deferred "second dimension", closed unbuilt #5138's fragment-marking design.
• Shape 3 (file instances as found) remains the honest default in the interim.

State: needs-user-decision → pm:queue (the queued work is the shape-2 half, jointly scoped with #5155).

---

Generated by Claude Code