Repository navigation
docs(v4): correct the version boundary on the coerce missing-key note - #6379
colinhacks wants to merge 1 commit into
Conversation
The note added in #5964 reads "Zod 3: { foo: false } / Zod 4: ZodError". Zod 4.0 through 4.3 return `{ foo: false }` just like v3 does; the absent-key rejection landed in 4.4.0 with #5661, which made the object parser treat a key as absent-able only when the field schema is optional on the input side. Name 4.4.0 as the boundary, inline the `.default()` escape hatch, and state the general rule — it is an `optin` rule, not a `z.coerce` rule, and it matches an inferred input type that has required the key since 4.0. Also pins the behavior for all five coercers in coerce.test.ts. optional.test.ts covers `z.undefined()` and undefined-bearing unions but nothing in the suite covered `z.coerce.*`, which is why the change reached users unannounced. Refs #5957.
There was a problem hiding this comment.
ℹ️ Boundary claim checks out against published releases. One scope question and one prose nit, neither blocking.
Reviewed changes — a docs-only correction to the z.coerce missing-key note plus a regression test; no runtime source is touched.
- Version boundary corrected to
4.4.0—changelog.mdx:383-395now dates the absent-key rejection tozod@4.4.0instead of the v3 → v4 boundary, inlines the.default(false)escape hatch, and states the underlyingoptinrule. - New
absent object key is not coercedtest —coerce.test.ts:161-188covers all five coercers under both jit andjitless: true, pins the exactinvalid_type/nonoptionalissue with an inline snapshot, and adds two positive controls (present-undefinedstill coerces;.default(false)still resolves).
I verified every factual claim rather than taking them on faith:
- Probed published packages directly:
4.0.0,4.1.13,4.2.1and4.3.6all return{ foo: false }forz.object({ foo: z.coerce.boolean() }).parse({});4.4.0and4.4.3throwinvalid_type/nonoptional. "Zod 3 through 4.3" / "Zod 4.4" is exact. tsc --strictagainst bothzod@4.0.0andzod@4.4.3rejectsconst a: z.input<typeof schema> = {}withTS2741: Property 'foo' is missing, so "has required the key since Zod 4.0" holds and the 4.4 change closed a runtime/type divergence that had been open since 4.0.- The general rule is stated accurately:
z.objectgates absent keys onel._zod.optin === "optional"and$InferObjectInputreads the same flag, so "optional on the input side" is true at both the runtime and type level, andz.coerce.*sets neither. - The test is real coverage, not theatre — its assertions invert across the 4.3/4.4 boundary, and the snapshot is exact rather than absorbing.
pnpm vitest run packages/zod/src/v4/classic/tests/coerce.test.tspasses 14 tests with no type errors. The comment-alignment padding in the code block is correct (cat -Aconfirms both values start at column 23).
ℹ️ A 4.3 → 4.4 note lives in a v3 → v4 migration guide, and api.mdx is still silent
changelog.mdx is front-mattered title: Migration guide / "upgrading from Zod 3 to Zod 4", and after this change line 383 is the only entry in the entire document scoped to a specific 4.x minor. Correcting it in place is strictly better than leaving it wrong, but someone upgrading 4.3 → 4.4 has no reason to open a v3 → v4 guide, so the discoverability gap the PR description identifies is narrowed rather than closed. Purely a scope call for you.
Technical details
# Absent-key rejection is undocumented outside the v3 → v4 migration guide
## Affected sites
- `packages/docs/content/v4/changelog.mdx:383` — correct after this PR, but the only minor-scoped entry in a document framed end-to-end as a v3 → v4 upgrade path.
- `packages/docs/content/api.mdx:28-108` — the canonical `### Coercion` reference. Documents that the input type is `unknown` and carries a Callout on surprising boolean coercion (`schema.parse(undefined); // => false`, line 86 — still true for a *top-level* parse), but says nothing about an absent object key being rejected. This is the page a 4.4 user lands on when they hit the behavior reported in #5957.
## Required outcome
- A 4.4 user reading the coercion reference should learn that `z.object({ foo: z.coerce.boolean() }).parse({})` throws and that `.default()` is the fix, without having to read a v3 migration guide.
## Suggested approach (optional)
- Two or three lines in the `api.mdx` "How coercion works in Zod" accordion, next to the existing `parse(undefined) // => false` example, drawing the present-vs-absent distinction. The migration-guide entry then stays purely historical.
## Open questions for the human
- Is the v3 → v4 migration guide the intended long-term home for minor-version behavior changes, or should those live in release notes / a separate versioned changelog?ℹ️ Nitpicks
changelog.mdx:395— "It matches the inferred input type" has an ambiguous antecedent; "It" could read as the rule or as the error. Your own PR description phrases it more clearly: "the runtime now matches an inferred input type that has required the key since 4.0."changelog.mdx:383vs:390— the prose sayszod@4.4.0while the code comment saysZod 4.4. Harmless, but4.4.0in both would read as one claim rather than two.
Claude Opus | 𝕏
|
Closing this — not adding a changelog note for the 4.4.0 optin change. It was an unintentional soundness issue that landed as a bug fix in a minor, not a documented breaking change. |

The coerce missing-key note that landed in #5964 dates the change to the v3 → v4 boundary:
Zod 4.0, 4.1, 4.2 and 4.3 all return
{ foo: false }, same as v3. The absent-key rejection landed in 4.4.0 with #5661, which made the object parser treat a key as absent-able only when the field schema is optional on the input side. As written the note tells a reader on 4.2 that their working code is broken, and gives someone upgrading 4.3 → 4.4 no signal that a minor bump moved behavior.Names 4.4.0 as the boundary, inlines the
.default(false)escape hatch, and states the general rule — it's anoptinrule rather than az.coercerule, and the runtime now matches an inferred input type that has required the key since 4.0.Also pins the behavior for all five coercers in
coerce.test.ts.optional.test.tscoversz.undefined()and undefined-bearing unions, but nothing coveredz.coerce.*, which is part of why the change reached users unannounced.Refs #5957.