Skip to content

docs: note that the JSON Schema emitter reads static optin - #6417

Merged
colinhacks merged 3 commits into
mainfrom
docs-optionality-json-schema-consumer
Aug 16, 2026
Merged

colinhacks merged 3 commits into
mainfrom
docs-optionality-json-schema-consumer

Conversation

@colinhacks

Copy link
Copy Markdown
Owner

objectProcessor is the one consumer of optin that has to read the static declaration rather than the runtime flag — io: "input" describes the declared input type, so catch, transform and preprocess all have to be resolved past. Nothing near the emitter said so, and the consumer table in wiki/optionality.md listed only $ZodObject, $ZodTuple and $ZodOptional.

That gap is what let #6409 and #6133 land seven minutes apart on opposite sides of the same question: #6409 stripped an output-typed catch value from the input schema while explicitly leaving requiredness on the runtime flag, and #6133 then had to rewrite the snapshot #6409 had just added.

Adds the emitter to the table with a section covering both halves — the emitted value via isTransforming, the requiredness via inputOptin — and points at it from inputOptin(). Also drops the stale in-flight branch reference in the doc header, and the "each with a single consumer" claim that the optin row already contradicted.

Docs plus one comment; no behavior change.

`objectProcessor` is the one consumer of `optin` that has to read the static
declaration rather than the runtime flag, because `io: "input"` describes the
declared input type. Nothing near the emitter said so, and #6409 and #6133
landed seven minutes apart taking opposite lines on the two halves of that
question: #6409 stripped an output-typed catch value from the input schema
while explicitly leaving requiredness on the runtime flag, and #6133 then had
to rewrite the snapshot #6409 had just added.

Add the emitter to the consumer table in wiki/optionality.md, with a section
covering the split and both halves of it, and point at that section from
inputOptin(). Also drop the stale in-flight branch reference in the header and
the "each with a single consumer" claim, which the optin row already
contradicted.
Copilot AI lite review requested due to automatic review settings August 16, 2026 21:50

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.

Important

The new section is accurate about objectProcessor, but two of its claims don't hold up against the current source: the "one consumer" framing misses tupleProcessor, and the closing #6409 sentence overstates what isTransforming does to catch values.

Reviewed changes — a docs-only PR (plus a two-line code comment) documenting that the JSON Schema emitter reads the static optin rather than the runtime flag. No behavioral surface, so the three-axes checks don't apply.

  • inputOptin comment — appends two lines above inputOptin in json-schema-processors.ts calling it the one consumer that must read the static value, pointing at wiki/optionality.md.
  • Stale branch reference dropped — the header no longer claims to reflect the in-flight fix-fallback-flag-and-preprocess branch. Correct; that was #5941's head ref and it's merged.
  • "each with a single consumer" dropped — correct, the optin row already listed three.
  • optin consumer table row — adds objectProcessor with a static-value annotation.
  • New ### The JSON Schema emitter reads the *static* value section — reproduces inputOptin, explains the policy, and cites #5003 / #6133 / #5939 / #5941 / #6409.

I checked every citation and they hold: inputOptin (both the pipe and the catch branch) came entirely from #6133 in 78b523f0, #5939 and #5941 did set the runtime flags, and the #5003 characterization is a fair paraphrase of the maintainer's own "what you can pass in vs what you should pass in" comment on that issue. The reproduced snippet matches json-schema-processors.ts:271-280.

⚠️ The tuple emitter has the same divergence, and it's unfixed and untested

Separate from the doc wording: tupleProcessor reading the runtime optin isn't just an incomplete sentence, it produces wrong output today. The preprocess case is the clear one — minItems: 1 agrees with neither the declared input type nor the runtime parser, which makes it the tuple-level twin of the bug #6133 fixed for objects. There's no test pinning it either way, so whichever direction is chosen won't be protected.

Worth deciding whether this PR just scopes its wording and files a follow-up, or whether the tuple gap gets fixed here. I'd lean toward the former to keep this docs-only, but the doc shouldn't assert uniqueness while the gap is open.

Technical details
# `tupleProcessor` reads runtime `optin` in input mode

## Affected sites
- `packages/zod/src/v4/core/json-schema-processors.ts:393-397` — `const optKey = ctx.io === "input" ? "optin" : "optout";` then a tail scan shrinking `minItems` while `_zod[optKey] === "optional"`. Direct runtime read, no `inputOptin` equivalent.
- `packages/zod/src/v4/classic/tests/to-json-schema.test.ts:1303-1366` — tuple `minItems` coverage exists for plain / `.rest()` / `.optional()` / `.default()` only. `.default()` cannot catch this class, because default genuinely makes the declared input optional (unlike catch/preprocess).
- `wiki/optionality.md:364-368` — the `## Tuples` section describes only the runtime parser's flag reads, never the emitter.

## Observed behavior (probed on `786efae6`)
```ts
z.toJSONSchema(z.tuple([z.string(), z.string().catch("x")]), { io: "input" });
// minItems: 1   — but z.input<> is [string, string]
// runtime .safeParse(["a"]) === true

z.toJSONSchema(z.tuple([z.string(), z.preprocess((v) => v, z.string())]), { io: "input" });
// minItems: 1   — but z.input<> is [string, string]
// runtime .safeParse(["a"]) === false   <-- matches neither the declared type nor the parser
```
The equivalent object schemas both emit `required: ["a", "b"]`, because `objectProcessor` goes through `inputOptin`.

## Required outcome
- Either scope the uniqueness claim so it describes what is true (`objectProcessor` is the one consumer that *does* resolve to the static value) and record the tuple gap, or bring `tupleProcessor` in line with `objectProcessor`.
- Whichever is chosen, `wiki/optionality.md` should not leave a reader believing the emitter handles this consistently across containers.

## Open questions for the human
- Is the `minItems` tail scan intended to track the runtime parser rather than the declared input type? If so that is a deliberate exception worth writing down, though the preprocess case is still wrong under that reading.
- Fix here, or follow-up issue? A fix touches `core/`, so it would need the three-axes treatment and tuple `minItems` snapshot updates.

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

Comment thread wiki/optionality.md Resolved
Comment thread wiki/optionality.md Resolved
Two corrections from review.

`objectProcessor` is not the only emitter consumer of `optin`. `tupleProcessor`
reads it in the same input branch to shrink `minItems`, and it reads the runtime
value with no resolution past transform or catch. That is a live divergence, not
just a wording gap:

  z.toJSONSchema(z.tuple([z.string(), z.preprocess(v => v, z.string())]), { io: "input" })
  // minItems: 1, but z.input<> is [string, string] and .safeParse(["a"]) rejects

Record it rather than assert consistency the emitter does not have. Left unfixed
here to keep this docs-only — the fix touches core/ and needs its own tuple
minItems snapshots.

The #6409 sentence also generalized too far. A plain catch keeps its `default`
under io: "input"; #6409 added catch to isTransforming's recursion, so only a
catch over a transforming schema loses it.
@colinhacks

Copy link
Copy Markdown
Owner Author

Both correct — fixed in cc7e845.

The tuple gap is real, so the doc now records it instead of asserting a consistency the emitter doesn't have. tupleProcessor's minItems scan reads the runtime flag, so z.tuple([z.string(), z.preprocess(v => v, z.string())]) emits minItems: 1 under io: "input" while z.input<> is [string, string] and .safeParse(["a"]) rejects — matching neither. For catch it at least tracks the parser. Leaving the fix out of this PR to keep it docs-only; it touches core/ and needs its own tuple minItems snapshots.

Also corrected the #6409 sentence. A plain catch keeps its default under io: "input"; #6409 added catch to isTransforming's recursion, so only a catch over a transforming schema loses it.

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

ℹ️ All three prior findings are addressed and probe-verified. One cross-reference nit inline.

Reviewed changes — cc7e845f reworks the new wiki section and the inputOptin comment in response to the previous review; the docs-only character is unchanged, so the three-axes checks still don't apply.

  • Scoped the "one consumer" claim — the section now opens with "consumes optin too, in two places" and attributes the static resolution to objectProcessor specifically. Accurate: optin is read at json-schema-processors.ts:280 (inputOptin) and :394 (tupleProcessor), and nowhere else in the emitter.
  • Documented the tuple gap — a new paragraph plus a runnable example showing z.tuple([z.string(), z.preprocess(v => v, z.string())]) emitting minItems: 1 under io: "input".
  • Corrected the #6409 sentence — the suggested wording was applied, so the text now says a catch loses its default only when it sits over a transforming inner.
  • Updated the line-13 table row — the optin "Consumed by" cell carries the same objectProcessor / tupleProcessor split.
  • Extended the inputOptin comment — now names the tupleProcessor divergence instead of asserting uniqueness.

I re-probed every factual claim in the new text on this branch and they all hold: the preprocess tuple emits minItems: 1 while .safeParse(["a"]) rejects; the catch tuple emits minItems: 1 while .safeParse(["a"]) succeeds; both object equivalents emit required: ["a","b"]. Tuple minItems coverage in to-json-schema.test.ts is plain / .rest() / .optional() / .default() / empty only, so "nothing pins either direction" is correct too.

ℹ️ The tuple divergence is now documented but untracked

The wiki now records that tupleProcessor emits minItems matching neither the declared input type nor the parser for the preprocess case, which is a real bug rather than a wording gap. Nothing in this PR files a follow-up or adds a test pinning either direction, so the next reader learns the behavior is wrong and unsettled with no thread to pull. Entirely a maintainer call — flagging it only so it doesn't get lost now that the doc makes it easy to forget.

Technical details
# Tuple emitter `minItems` divergence is documented, not tracked

## Affected sites
- `packages/zod/src/v4/core/json-schema-processors.ts:394-397` — `const optKey = ctx.io === "input" ? "optin" : "optout"` plus the tail scan reading `_zod[optKey]` directly. No `inputOptin` equivalent.
- `packages/zod/src/v4/classic/tests/to-json-schema.test.ts` (~1302-1365) — tuple `minItems` tests cover plain / `.rest()` / `.optional()` / `.default()` / empty. `.default()` cannot catch this class, since default genuinely makes the declared input optional.

## Required outcome
- A durable tracker for the tuple gap (follow-up issue, or a test that pins the current output so a future change to `tupleProcessor` is a visible decision rather than an accident).

## Open questions for the human
- Follow-up issue, or leave it as a doc note? Either is defensible for a docs PR; the doc alone leaves no signal in CI.
- If it does get fixed later, it is a `core/` behavior change: three-axes treatment plus tuple `minItems` snapshot updates.

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

The cross-reference named "Static/runtime divergence", which covers the
parser-level catch/transform/preprocess split and never mentions the emitter.
The section that documents this comment is the one added here.

@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 found. The last open thread is addressed; nothing else changed.

Reviewed changes — 1ed828bd is a single-line edit to the inputOptin comment, retargeting its cross-reference. Still docs-only, so the three-axes checks don't apply.

  • Retargeted the wiki cross-reference — the comment above inputOptin now points at "The JSON Schema emitter reads the *static* value" instead of "Static/runtime divergence". The quoted string matches the heading this PR adds at wiki/optionality.md:116 exactly, so the reference resolves; the old target (:57) covers the parser-level split and never mentions the emitter.

That was the only outstanding item, and it was the suggested wording applied verbatim. The wiki text and the table row are byte-identical to cc7e845f, which I probe-verified last run, so nothing there needed re-checking.

The tuple minItems divergence remains documented-but-untracked. I raised that last run as informational and it's still a maintainer call, so I'm not re-opening it here — noting only that it's the one loose end this PR knowingly leaves behind.

Pullfrog  | View workflow run | Using Claude Opus | 𝕏

@colinhacks
colinhacks merged commit 2abc9e0 into main Aug 16, 2026
11 checks passed
@colinhacks
colinhacks deleted the docs-optionality-json-schema-consumer branch August 16, 2026 22:15

This branch was successfully deployed

1 active deployment
Preview – zod-v4 — 1ed828bd Deployed Aug 16, 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