Repository navigation
docs: note that the JSON Schema emitter reads static optin - #6417
Conversation
`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.
There was a problem hiding this comment.
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.
inputOptincomment — appends two lines aboveinputOptininjson-schema-processors.tscalling it the one consumer that must read the static value, pointing atwiki/optionality.md.- Stale branch reference dropped — the header no longer claims to reflect the in-flight
fix-fallback-flag-and-preprocessbranch. Correct; that was #5941's head ref and it's merged. - "each with a single consumer" dropped — correct, the
optinrow already listed three. optinconsumer table row — addsobjectProcessorwith a static-value annotation.- New
### The JSON Schema emitter reads the *static* valuesection — reproducesinputOptin, 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.Claude Opus | 𝕏
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.
|
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. Also corrected the |
There was a problem hiding this comment.
ℹ️ 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
optintoo, in two places" and attributes the static resolution toobjectProcessorspecifically. Accurate:optinis read atjson-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())])emittingminItems: 1underio: "input". - Corrected the #6409 sentence — the suggested wording was applied, so the text now says a catch loses its
defaultonly when it sits over a transforming inner. - Updated the line-13 table row — the
optin"Consumed by" cell carries the sameobjectProcessor/tupleProcessorsplit. - Extended the
inputOptincomment — now names thetupleProcessordivergence 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.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.
There was a problem hiding this comment.
✅ 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
inputOptinnow points at"The JSON Schema emitter reads the *static* value"instead of"Static/runtime divergence". The quoted string matches the heading this PR adds atwiki/optionality.md:116exactly, 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.
Claude Opus | 𝕏

objectProcessoris the one consumer ofoptinthat has to read the static declaration rather than the runtime flag —io: "input"describes the declared input type, socatch,transformandpreprocessall have to be resolved past. Nothing near the emitter said so, and the consumer table inwiki/optionality.mdlisted only$ZodObject,$ZodTupleand$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 viainputOptin— and points at it frominputOptin(). Also drops the stale in-flight branch reference in the doc header, and the "each with a single consumer" claim that theoptinrow already contradicted.Docs plus one comment; no behavior change.