content/docs/blocks/forms.mdx「Add Validation」示例教的是第三种 validation 方言:扁平字符串 `pattern` + 从未存在过的兄弟键 `message`,`objectui validate` 现已具名拒绝

[os-support-ai]

发现于 #5186 的实施(对齐 FieldConstraintsSchema 到 FieldValidationRules 时按规则消费半径扫描文档示例)。Filed unassigned, not claiming. #5186 remains open until its own PR lands; this card is the docs-only follow-up.

现象

content/docs/blocks/forms.mdx 的「Add Validation」小节(≈行 41-53)教读者写:

{
 "type": "input",
 "name": "email",
 "validation": {
 "pattern": "^[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}$",
 "message": "Please enter a valid email address"
 }
}

这是第三种方言,两个声明面都没有它:

1. pattern 是扁平字符串 —— 公开 TS 契约 FieldValidationRules.pattern 是 { value, message } 对象(手写 FieldValidationRules 在唯一读点既不校验也不归一:pattern.value 写成 string(类型明确允许)被 react-hook-form 静默忽略,未识别的规则名同样静默丢弃 #5099 后 value 收成 RegExp);FormFieldSchema.validation 的 zod 镜像(FieldConstraintsSchema)与 FieldValidationRules 形状完全不符:拒绝 TS 契约合法的对象形、放行渲染器从不读的扁平形 #5186 落地后 zod 面也已对齐,objectui validate 会对这份示例的 pattern 具名拒绝并指引元数据路线(FieldSchema.pattern)。
2. 兄弟键 message 在 FieldValidationRules 与 FieldConstraintsSchema 里从未存在过(消息一直住在各规则对象内部),任一时期的 zod 面都会把它静默 strip。

即便在 #5186 之前,这份示例也从未跑过任何校验:form.tsx 的读点把 validation 原样展开给 react-hook-form,react-hook-form 只在 pattern.value instanceof RegExp 时才执行 pattern 规则 —— 照抄示例的读者得到的是「看起来有校验、实际零执行」(#5099 症状),现在则是 validate 时被具名拒绝。同族先例:#5118(plugin-form.mdx 的 validation 数组拼法,已关)修的是另一文件的另一方言,没有覆盖本文件。

修法方向(docs-only)

JSON 面携带不了 RegExp,诚实的教法是指去元数据路线:字段声明上的 FieldSchema.pattern(字符串,由 @object-ui/fields 的 buildValidationRules 编译),或在 TS 示例里用 pattern: { value: /…/, message: '…' }。顺带全文扫一遍 content/docs/blocks/forms.mdx 是否还有同方言的其它示例。

复核:

sed -n '41,53p' content/docs/blocks/forms.mdx

---

Generated by Claude Code

[os-support-ai]

Triage: lands in content/docs/blocks/forms.mdx (docs-only) — promoted to pm:queue, type Bug: the published example teaches a validation dialect neither declared surface ever had, and objectui validate now rejects it by name after #5186's alignment, so the tutorial breaks first-runs. Fix direction is in the body (teach the metadata route FieldSchema.pattern, or the { value: RegExp, message } object form in TS examples; sweep the file for sibling examples of the same dialect).

Serial note: #5186 is in flight (pm:dispatched) but touches the zod mirror, not this docs file — no file-surface overlap; do respect its outcome as the source of truth for what the accepted shape is (claim after it lands or re-read its PR before writing). Size/model suggestion: S, sonnet.

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round 6
Session: session_01RV6yuVCxymHYE16PL9vQkE
Branch: claude/issue-5229-forms-mdx-validation-dialect
Worktree: objectui-issue-5229
Domain: repo:objectui (execution seat)
File surface: content/docs/blocks/forms.mdx. ⛔ OUT: packages/types/** (#5186 landed today — the contract is now correct and is the reference, not a thing to adjust), packages/fields/**, examples/hello-world/** (#5236, dispatched this round), packages/cli (#5237), packages/auth + app-shell/providers (#5198).
Container & model: S, mode:subagent, model: opus — docs-only, but the teaching decision (which of two correct routes to show for which face) is judgement, and getting it wrong publishes a fourth dialect.
Clause-②: no — docs only; no code, no contract.
Serial constraints cleared: nothing open touches content/docs/blocks/**. #5186's PR5230 merged this round, so the contract this card must teach is settled and on main.

Why this is urgent now rather than ordinary docs tidying

PR5230 landed today and changed this example from quietly wrong to loudly wrong. Before it, objectui validate accepted the documented pattern and react-hook-form then silently dropped it — the reader got "looks validated, executes nothing" (#5099's symptom). After it, objectui validate rejects this example by name and points at the metadata route.

That is a net improvement — a loud rejection of something that never worked beats silence — but it means the published documentation now teaches a shape our own tool refuses. A reader who copies the documented example gets an error. That is the state this card closes.

The defect — three dialects, and the docs teach the one that never existed

content/docs/blocks/forms.mdx "Add Validation" (≈ lines 41–53) teaches:

"validation": {
 "pattern": "^[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}$",
 "message": "Please enter a valid email address"
}

Both keys are wrong, in different ways:

1. pattern as a flat string — the public TS contract FieldValidationRules.pattern is a { value, message } object, and since 手写 FieldValidationRules 在唯一读点既不校验也不归一:pattern.value 写成 string(类型明确允许)被 react-hook-form 静默忽略,未识别的规则名同样静默丢弃 #5099 value is narrowed to a compiled RegExp. As of PR5230 the zod face matches, and rejects a string pattern.value by name with guidance toward FieldSchema.pattern.
2. A sibling message key — this has existed in neither declaration, ever. Messages have always lived inside each rule object. Any zod face of any vintage strips it silently.

The teaching decision — this is the part that needs care

JSON cannot carry a RegExp. So on the JSON face the documented shape is not merely mis-spelled, it is inexpressible: there is no correct way to write a pattern rule in a JSON form block. Rewriting it as "pattern": { "value": "…", "message": "…" } would publish a fourth dialect that objectui validate also rejects — by the same named rejection, for the same reason.

The honest routes, and they are face-dependent:

• JSON / YAML metadata → the field metadata route: FieldSchema.pattern (a string), which @object-ui/fields' buildValidationRules compiles into a RegExp before it ever reaches the form's validation shape.
• TS / programmatic → pattern: { value: /…/, message: '…' } directly, since a real RegExp is in hand.

Pick per the surrounding example's face — if the section's examples are JSON, teach the metadata route there. ⛔ Do not show a JSON snippet with a pattern object and imply it validates.

The other rules (minLength / maxLength / min / max) are { value, message } and are expressible in JSON; required is boolean | string where a string is the message. If the section teaches any of those, they can be shown correctly in place.

Scope

• Sweep the whole file, not just lines 41–53 — the card asks for this explicitly. Report every occurrence of the flat dialect or a stray sibling message you find, and whether you fixed each.
• ⛔ Do not touch packages/types. The contract is correct as of PR5230 and is your reference. If the docs and the contract disagree, the docs are wrong.
• Same-family precedent, already closed: content/docs/plugins/plugin-form.mdx 的 Form Field 参考块与「Form with Validation」示例是 #5075 的文档站镜像:validation 数组拼法让校验静默失效,ValidationRule 全仓不存在 #5118 fixed a different dialect in plugin-form.mdx. Read it for how that one phrased the correction, but note it did not cover this file.

Verification

Docs-only, so the pin is the tool's verdict, not a unit test. Show the before and after of objectui validate (or the doc-snippet gate, if it reaches this file) over the example you change: rejected-by-name before, accepted after. If no gate covers content/docs/blocks/**, say so plainly — that is itself worth knowing, and #5174 already records that check-doc-snippet-types.mjs collects only .mdx under content/docs, so check whether this file is actually gated before claiming it is.

If the corrected example cannot be validated by any tool we ship, report that: a docs fix nothing can check is a weaker deliverable and the maintainer should know.

Gates

Derive from your diff. scripts/pm/dispatch-gates.mjs is objectstack-only. Expect Internal Docs Link Check, Doc Snippet Type Check, Build Docs, Control Byte Scan. Changeset almost certainly not required for content/docs/** — run check-changeset-presence.mjs and report its actual verdict rather than assuming.

⛔ Do not background a long check and end your turn.

Deliver

Draft PR against main, first body line Fixes #5229. Return the JSON report and post it as a comment whose first line is the literal <!-- os-dev-report --> marker.

---

Generated by Claude Code