Skip to content

docs(v4): correct the version boundary on the coerce missing-key note - #6379

Closed
colinhacks wants to merge 1 commit into
mainfrom
fix/5957-coerce-missing-key-changelog
Closed

colinhacks wants to merge 1 commit into
mainfrom
fix/5957-coerce-missing-key-changelog

Conversation

@colinhacks

Copy link
Copy Markdown
Owner

The coerce missing-key note that landed in #5964 dates the change to the v3 → v4 boundary:

// Zod 3: { foo: false }
// Zod 4: ZodError: Invalid input: expected nonoptional, received undefined

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 an optin rule rather than a z.coerce rule, 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.ts covers z.undefined() and undefined-bearing unions, but nothing covered z.coerce.*, which is part of why the change reached users unannounced.

Refs #5957.

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.
Copilot AI lite review requested due to automatic review settings August 12, 2026 18:46

Copilot AI 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.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@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.

ℹ️ 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-395 now dates the absent-key rejection to zod@4.4.0 instead of the v3 → v4 boundary, inlines the .default(false) escape hatch, and states the underlying optin rule.
  • New absent object key is not coerced test — coerce.test.ts:161-188 covers all five coercers under both jit and jitless: true, pins the exact invalid_type / nonoptional issue with an inline snapshot, and adds two positive controls (present-undefined still 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.1 and 4.3.6 all return { foo: false } for z.object({ foo: z.coerce.boolean() }).parse({}); 4.4.0 and 4.4.3 throw invalid_type / nonoptional. "Zod 3 through 4.3" / "Zod 4.4" is exact.
  • tsc --strict against both zod@4.0.0 and zod@4.4.3 rejects const a: z.input<typeof schema> = {} with TS2741: 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.object gates absent keys on el._zod.optin === "optional" and $InferObjectInput reads the same flag, so "optional on the input side" is true at both the runtime and type level, and z.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.ts passes 14 tests with no type errors. The comment-alignment padding in the code block is correct (cat -A confirms 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:383 vs :390 — the prose says zod@4.4.0 while the code comment says Zod 4.4. Harmless, but 4.4.0 in both would read as one claim rather than two.

Pullfrog  | Fix it ➔ | View workflow run | Using Claude Opus | 𝕏

@colinhacks

Copy link
Copy Markdown
Owner Author

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.

@colinhacks colinhacks closed this Aug 13, 2026
@colinhacks
colinhacks deleted the fix/5957-coerce-missing-key-changelog branch August 13, 2026 05:03

This branch was successfully deployed

1 active deployment
Preview – zod-v4 — 3563d633 Deployed Aug 12, 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