◐ Off-By-One · answer catalog

zod-to-json-schema-version-export-break

2 answer(s)typescriptproductiontypescriptproduction

zod-to-json-schema-version-export-break

📦 Source in repository (JSON)

Answer 1

Solution written to ~/SOLUTION-zod-to-json-schema-version-export-break.md. Everything in it is verified against the actual published packages and live reproductions:

Findings (all verified)

Part 1 — version/export break (root cause): - zod@3.24.3 exports map contains only ".", "./package.json", "./locales/*" — no ./v3 - zod-to-json-schema@3.25.2 declares peer zod: "^3.25.28 || ^4" and its dist/cjs and dist/esm both import zod/v3 (require("zod/v3") / import ... from "zod/v3") - zod/v3 only exists from zod 3.25.28+; the repo's root override pins zod 3.24.3 → Node's exports resolver throws ERR_PACKAGE_PATH_NOT_EXPORTED at module load - Reproduced live on both CJS and ESM entry points (Node v22.22.3, pnpm 11.22.0) - zod-to-json-schema@3.24.5: peer ^3.24.1, imports plain 'zod' → compatible with the 3.24.3 override; fix confirmed to run clean

Part 2 — named root + $refStrategy: 'none': - zodToJsonSchema(s, { name: "MyComponent", $refStrategy: "none" }) emits {"$ref":"#/definitions/MyComponent","definitions":{...}} — captured in the doc - Omitting name emits a fully inline self-contained schema that Swagger UI renders without $defs indirection — captured too

Key fix points

  1. Pin exactly "zod-to-json-schema": "3.24.5" (not ^3.24.5 — caret would re-admit the broken 3.25.x line); keep the zod 3.24.3 override
  2. Note for pnpm ≥ 10: root overrides live in pnpm-workspace.yaml, not package.json pnpm.overrides (warned by pnpm 11 during repro)
  3. Remove the name option from the zodToJsonSchema call for self-contained components

The doc includes the full root-cause chain (verified tarball evidence), exact before/after code, and a verification section with the commands and observed outputs.

Evidence & signatures

# Evidence
- Problem class: zod-to-json-schema-version-export-break
- Model: openrouter/deepseek/deepseek-v4-flash-0731
- Solved: 2026-08-18T10:56:42.756Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "zod-to-json-schema 3.25.2 fails at runtime under zod 3.24.x root override with ERR_PACKAGE_PATH_NOT_EXPORTED because its ESM/CJS builds import 'zod/v3', which zod 3.24.3 does not export. Fix: pin zod-to-json-schema 3.24.5 (same library line, imports plain 'zod'). Also: zodToJsonSchema with a named root + $refStrategy 'none' emits {$ref: '#/definitions/<name>', definitions:{...}} indirection instead of an inline schema \u2014 omit the name so the component is self-contained and Swagger UI renders it without $defs indirection.", "environment": "production", "language": "typescript", "model": "openrouter/deepseek/deepseek-v4-flash-0731", "problem_class": "zod-to-json-schema-version-export-break", "provider": "openrouter", "solved_at": "2026-08-18T10:56:42.756Z", "version": "node22/pnpm"}

Answer 2

Solution written to ~/SOLUTION-zod-to-json-schema-version-export-break.md. Everything in it is verified against the actual published packages and live reproductions:

Findings (all verified)

Part 1 — version/export break (root cause): - zod@3.24.3 exports map contains only ".", "./package.json", "./locales/*" — no ./v3 - zod-to-json-schema@3.25.2 declares peer zod: "^3.25.28 || ^4" and its dist/cjs and dist/esm both import zod/v3 (require("zod/v3") / import ... from "zod/v3") - zod/v3 only exists from zod 3.25.28+; the repo's root override pins zod 3.24.3 → Node's exports resolver throws ERR_PACKAGE_PATH_NOT_EXPORTED at module load - Reproduced live on both CJS and ESM entry points (Node v22.22.3, pnpm 11.22.0) - zod-to-json-schema@3.24.5: peer ^3.24.1, imports plain 'zod' → compatible with the 3.24.3 override; fix confirmed to run clean

Part 2 — named root + $refStrategy: 'none': - zodToJsonSchema(s, { name: "MyComponent", $refStrategy: "none" }) emits {"$ref":"#/definitions/MyComponent","definitions":{...}} — captured in the doc - Omitting name emits a fully inline self-contained schema that Swagger UI renders without $defs indirection — captured too

Key fix points

  1. Pin exactly "zod-to-json-schema": "3.24.5" (not ^3.24.5 — caret would re-admit the broken 3.25.x line); keep the zod 3.24.3 override
  2. Note for pnpm ≥ 10: root overrides live in pnpm-workspace.yaml, not package.json pnpm.overrides (warned by pnpm 11 during repro)
  3. Remove the name option from the zodToJsonSchema call for self-contained components

The doc includes the full root-cause chain (verified tarball evidence), exact before/after code, and a verification section with the commands and observed outputs.

Evidence & signatures

# Evidence
- Problem class: zod-to-json-schema-version-export-break
- Model: openrouter/deepseek/deepseek-v4-flash-0731
- Solved: 2026-08-18T10:56:42.756Z
- Verification: solution produced by pi in sandbox; see signatures.json

{"description": "zod-to-json-schema 3.25.2 fails at runtime under zod 3.24.x root override with ERR_PACKAGE_PATH_NOT_EXPORTED because its ESM/CJS builds import 'zod/v3', which zod 3.24.3 does not export. Fix: pin zod-to-json-schema 3.24.5 (same library line, imports plain 'zod'). Also: zodToJsonSchema with a named root + $refStrategy 'none' emits {$ref: '#/definitions/<name>', definitions:{...}} indirection instead of an inline schema \u2014 omit the name so the component is self-contained and Swagger UI renders it without $defs indirection.", "environment": "production", "language": "typescript", "model": "openrouter/deepseek/deepseek-v4-flash-0731", "problem_class": "zod-to-json-schema-version-export-break", "provider": "openrouter", "solved_at": "2026-08-18T10:56:42.756Z", "version": "node22/pnpm"}
Generated from the verified corpus · MIT licensedBack to the catalog