Skip to content

docs(v4): document coerce missing-key breaking change - #5964

Merged
colinhacks merged 1 commit into
colinhacks:mainfrom
dokson:docs-coerce-missing-key
Aug 12, 2026
Merged

colinhacks merged 1 commit into
colinhacks:mainfrom
dokson:docs-coerce-missing-key

Conversation

@dokson

@dokson dokson commented May 6, 2026

Copy link
Copy Markdown
Contributor

Refs #5957.

The v4 object parser checks required keys before delegating to field validators, so a z.coerce.* field on an object schema now rejects a missing key with expected: \"nonoptional\" instead of coercing `undefined`. This is intentional (and the only coherent choice across all coercers — String(undefined) → \"undefined\", Number(undefined) → NaN), but it wasn't called out in the migration guide. Adds a short note next to the existing z.coerce section pointing users to .default().

Test plan

  • Renders correctly in fumadocs (no syntax errors in the mdx)

@pullfrog

pullfrog Bot commented May 6, 2026 •

Copy link
Copy Markdown
Contributor

TL;DR — Documents a v4 breaking change where z.coerce.* fields on object schemas now reject missing keys instead of coercing undefined, pointing users to .default() for explicit fallbacks.

Key changes

  • Document z.coerce missing-key behavior — Adds a note and example to the v4 changelog explaining that coercion no longer sees missing object properties, directing users to .default().

Summary | 1 file | 1 commit | base: main ← docs-coerce-missing-key

Before: Changelog silently omitted that z.object({ foo: z.coerce.boolean() }).parse({}) went from { foo: false } in v3 to a nonoptional ZodError in v4.
After: A short paragraph plus a runnable example calls out the new behavior next to the existing z.coerce section, with .default() recommended as the explicit fallback.

The v4 object parser checks required keys before delegating to field validators, so z.coerce.* never observes a missing property. The note frames this as intentional — the alternative (String(undefined) → "undefined", Number(undefined) → NaN) would be incoherent across coercers. Refs #5957.

packages/docs/content/v4/changelog.mdx

Pullfrog  | View workflow run | via Pullfrog | Using Claude Opus | 𝕏

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important

Good direction — this is genuinely missing from the migration guide. Two small tweaks before merging: the prose leans on implementation detail (and is actually inverted — the field schema does run; the object parser then discards the result and emits a nonoptional issue), and the quoted error string is missing the Invalid input: prefix that users actually see. The issue reporter on #5957 already flagged the "object parser / delegating" framing as more confusing than just describing the behavior. Matching the register of the neighboring entries (observable behavior + // Zod 3: / // Zod 4: delta) should close the gap.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using Claude Opus | 𝕏

Comment thread packages/docs/content/v4/changelog.mdx Resolved
Comment thread packages/docs/content/v4/changelog.mdx Resolved

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No new issues. Reviewed the following changes:

  • Trimmed the prose to a single observable-behavior sentence, dropping the implementation-detail framing.
  • Updated the Zod 4 code comment to quote the real error string (Invalid input: expected nonoptional, received undefined).

Prior review feedback:

  • Trim internals-leaning prose to observable behavior — addressed
  • Quote the actual emitted error message verbatim — addressed

Pullfrog  | View workflow run | Using Claude Opus | 𝕏

@colinhacks
colinhacks merged commit e177a0e into colinhacks:main Aug 12, 2026
7 checks passed
@dokson
dokson deleted the docs-coerce-missing-key branch October 2, 2026 16:20

This branch was successfully deployed

1 active deployment
Preview – zod-v4 — 237092e6 Deployed May 6, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants