Add `.toJSONSchema()` method #5477

colinhacks · 2025-11-25T03:13:14Z

No description provided.

colinhacks · 2025-11-25T06:10:33Z

cc @claude review this

claude · 2025-11-25T06:10:46Z

Claude finished @colinhacks's task —— View job

Code Review: `.toJSONSchema()` Method Implementation

I've completed a thorough review of this PR which adds instance method support for JSON Schema generation alongside the existing static function. Here's my analysis:

Architecture & Design ✅

Excellent refactoring that separates concerns cleanly:

to-json-schema.ts (551 lines) - Core orchestration logic (context, processing, def extraction, finalization)
json-schema-processors.ts (666 lines) - Individual type processors (string, number, object, union, etc.)
Original implementation preserved in to-json-schema-old.ts for reference

This architecture is much more maintainable than the previous 1008-line monolithic class. The processor pattern allows for:

Easy addition of new type processors
Clear separation of concerns
Better testability
Potential for custom processor overrides

Implementation Highlights ✅

Dual API Support:

Static: z.toJSONSchema(schema, params)
Instance: schema.toJSONSchema(params)
Both produce identical output (confirmed by tests in to-json-schema-methods.test.ts)

Standard Schema Integration:

Properly implements StandardJSONSchemaV1 interface
Adds ~standard.jsonSchema.input() and ~standard.jsonSchema.output() methods
Non-enumerable property prevents pollution of schema objects

Key improvements:

Changed from class-based (JSONSchemaGenerator) to functional API
Normalized target versions (draft-4 → draft-04, draft-7 → draft-07) for consistency
Added extensibility through processors parameter
Better handling of cycles and reused schemas

Test Coverage ✅

Comprehensive testing:

439 lines of new tests in to-json-schema-methods.test.ts covering:
- All primitive types
- String formats and validations
- Number validations
- Complex types (objects, arrays, unions, tuples)
- Edge cases (cycles, defaults, optional/nullable)
Standard Schema compliance tests
Parity tests ensuring static and instance methods match

Issues Found 🔍

1. Console.warn in old implementation (Minor)

to-json-schema-old.ts:851 contains:

console.warn(`Invalid target: ${this.target}`);

While this is in the "old" file kept for reference, per CLAUDE.md rules:

No log statements (console.log, debugger) in tests or production code

Recommendation: If to-json-schema-old.ts is meant to be kept in the codebase (not just temporarily), remove the console.warn. If it's temporary, consider removing the entire file before merging.

2. Type safety concern (Minor)

In to-json-schema.ts:153-155:

const overrideSchema = schema._zod.toJSONSchema?.(); if (overrideSchema) { result.schema = overrideSchema as any; // <-- Using 'as any' }

Recommendation: Define a proper return type for toJSONSchema in the schema internals interface rather than using as any.

3. Comment typo (Trivial)

to-json-schema.ts:36:

/** Whether to extract the `"input"` or `"output"` type. Relevant to transforms, Error converting schema to JSONz, defaults, coerced primitives, etc.

Issue: "Error converting schema to JSONz" appears to be a typo or artifact. Should likely be removed or clarified.

4. Processor injection pattern (Design question)

Each schema type manually injects its processor in the constructor:

inst._zod.processJSONSchema = (ctx, json, params) => processors.stringProcessor(inst, ctx as any, json, params);

This pattern is repeated ~30 times across schema constructors with ctx as any casts.

Questions:

Could this be automated/centralized to avoid repetition?
The as any casts suggest a type mismatch - can the types be aligned?
What's the benefit of instance methods over just passing processors as a record?

5. Missing documentation

The new .toJSONSchema() method lacks JSDoc comments explaining:

What it does
What parameters it accepts
What it returns
How it differs from z.toJSONSchema()

Recommendation: Add comprehensive JSDoc to the method signature in the ZodType interface.

Performance Considerations ⚡

Potential concern: Each schema instance now carries processor closures that bind inst:

inst._zod.processJSONSchema = (ctx, json, params) => processors.stringProcessor(inst, ctx as any, json, params);

This creates a new closure for every schema instance. For codebases with thousands of schema instances, this could impact memory.

Alternative approach: Keep processors pure (no instance binding), pass schema as parameter, and use a centralized processor lookup by def.type.

Code Quality ✅

Strengths:

Clean separation of concerns
Consistent error handling
Proper TypeScript typing (mostly)
No obvious security issues
Good use of functional programming patterns
Comprehensive test coverage

Weaknesses:

Heavy use of as any casts (type safety gaps)
Repetitive processor injection code
Some incomplete comments/documentation

Standard Schema Compliance ✅

Correctly implements the Standard Schema v1 JSON Schema extension:

✅ ~standard.jsonSchema.input() method
✅ ~standard.jsonSchema.output() method
✅ Accepts { target, libraryOptions } parameters
✅ Returns JSON Schema object
✅ Non-enumerable ~standard property

Recommendations

Before merging:

✅ Keep: The refactored architecture is excellent
🔧 Fix: Remove or clarify the "Error converting schema to JSONz" comment
🔧 Consider: Remove to-json-schema-old.ts if not needed long-term (or remove console.warn)
📝 Add: JSDoc documentation for .toJSONSchema() method
🔍 Review: Whether the processor injection pattern can be simplified/centralized
🔍 Review: Type safety improvements to reduce as any usage

For future consideration:

Benchmark memory usage of processor closures vs. centralized lookup
Consider making processors pluggable for custom schema types
Document the migration path from v3 to v4 JSON Schema generation

Summary

This is a high-quality PR that significantly improves the JSON Schema generation architecture. The refactoring from a monolithic class to composable processors is excellent. The dual API (static + instance method) provides great DX. Test coverage is comprehensive.

The issues identified are mostly minor (comments, type safety, documentation). The code is production-ready with small improvements.

Overall: ✅ Approved with minor suggestions

This reverts commit 3e8ba43.

Copilot

Pull request overview

This PR adds a .toJSONSchema() method to Zod schemas and refactors the JSON Schema generation from a class-based to a functional approach. The changes include:

Refactored JSONSchemaGenerator class to use functional approach with processor pattern
Added .toJSONSchema() instance method to all Zod schema types
Added support for StandardJSONSchemaV1 interface with ~standard.jsonSchema properties
Created separate processor functions for each schema type in new json-schema-processors.ts file

Key Changes

Separated JSON Schema generation logic into modular processor functions
Normalized target versions to use hyphenated format ("draft-04", "draft-07")
Made legacy JSONSchemaGenerator class a wrapper around new functional implementation
Added comprehensive test coverage for new .toJSONSchema() methods

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`packages/zod/src/v4/core/json-schema-processors.ts`	New file containing processor functions for each schema type
`packages/zod/src/v4/core/to-json-schema.ts`	Refactored to functional approach, added support for StandardJSONSchema
`packages/zod/src/v4/core/to-json-schema-old.ts`	Copy of original implementation for reference
`packages/zod/src/v4/core/standard-schema.ts`	Added StandardJSONSchemaV1 and StandardTypedV1 interfaces
`packages/zod/src/v4/core/schemas.ts`	Added `processJSONSchema` hook to schema internals
`packages/zod/src/v4/classic/schemas.ts`	Added `toJSONSchema` method and `~standard.jsonSchema` to all schema types
`packages/zod/src/v4/classic/tests/to-json-schema-methods.test.ts`	New comprehensive tests for `.toJSONSchema()` methods
`packages/zod/src/v4/classic/tests/to-json-schema.test.ts`	Updated import path from `zod/v4` to `zod`
`packages/zod/src/v4/classic/tests/standard-schema.test.ts`	Added tests for StandardJSONSchemaV1 conformance

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/zod/src/v4/core/to-json-schema.ts

packages/zod/src/v4/classic/tests/to-json-schema-methods.test.ts

packages/zod/src/v4/core/to-json-schema.ts

packages/zod/src/v4/core/json-schema-processors.ts

colinhacks · 2025-12-13T20:07:54Z

cc @pullfrog review

pullfrog

Strong refactoring that improves architecture. Found 2 critical bugs with draft-04 handling, import organization issues, and opportunities for better documentation.

^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ pullfrog.com ｜ 𝕏}

pullfrog · 2025-12-13T20:10:37Z

packages/zod/src/v4/core/json-schema-processors.ts

+ }
+ if (typeof minimum === "number") {
+ json.minimum = minimum;
+ if (typeof exclusiveMinimum === "number" && ctx.target !== "draft-04") {


Critical bug: Should be "draft-04" (hyphenated). initializeContext normalizes "draft-4" → "draft-04", so this condition will never match, breaking exclusive minimum handling for draft-04 schemas.

pullfrog · 2025-12-13T20:10:37Z

packages/zod/src/v4/core/json-schema-processors.ts

+ }
+ if (typeof maximum === "number") {
+ json.maximum = maximum;
+ if (typeof exclusiveMaximum === "number" && ctx.target !== "draft-04") {


Critical bug: Should be "draft-04" (hyphenated), same issue as line 72 but for exclusive maximum.

pullfrog · 2025-12-13T20:10:37Z

packages/zod/src/v4/core/json-schema-processors.ts

+ } else {
+ if (vals.every((v) => typeof v === "number")) json.type = "number";
+ if (vals.every((v) => typeof v === "string")) json.type = "string";
+ if (vals.every((v) => typeof v === "boolean")) json.type = "string";


Bug: Sets json.type = "string" for all-boolean literals. Should be "boolean". This incorrectly marks boolean literal unions.

pullfrog · 2025-12-13T20:10:37Z

packages/zod/src/v4/core/to-json-schema.ts

- return seen.schema;
- }
+ // custom method overrides default behavior
+ const overrideSchema = schema._zod.toJSONSchema?.();


The custom override (schema._zod.toJSONSchema?.()) bypasses all metadata, override hooks, and transform checks. Consider documenting this behavior, or applying metadata even when custom override is present.

pullfrog · 2025-12-13T20:10:37Z

packages/zod/src/v4/core/to-json-schema.ts

+ * Creates a toJSONSchema method for a schema instance.
+ * This encapsulates the logic of initializing context, processing, extracting defs, and finalizing.
+ */
+export const createToJSONSchemaMethod =


Why does createToJSONSchemaMethod default processors to {} while the main toJSONSchema uses allProcessors? This seems like it would break schema conversion. Needs documentation or reconsideration.

pullfrog · 2025-12-13T20:10:37Z

packages/zod/src/v4/classic/schemas.ts


 export const ZodType: core.$constructor<ZodType> = /*@__PURE__*/ core.$constructor("ZodType", (inst, def) => {
 core.$ZodType.init(inst, def);
+ Object.assign(inst["~standard"], {


Assigns to inst["~standard"] without checking if it exists. If core.$ZodType.init doesn't initialize this property, this will fail. Verify initialization order.

pullfrog · 2025-12-13T20:10:37Z

packages/zod/src/v4/core/json-schema-processors.ts

+
+export const pipeProcessor: Processor<schemas.$ZodPipe> = (schema, ctx, _json, params) => {
+ const def = schema._zod.def as schemas.$ZodPipeDef;
+ const innerType = ctx.io === "input" ? (def.in._zod.def.type === "transform" ? def.out : def.in) : def.out;


Complex transform handling logic. Add comment explaining why def.in._zod.def.type === "transform" requires using def.out for input mode.

pullfrog · 2025-12-13T20:10:48Z

Review Complete

Reviewed PR #5477: Add .toJSONSchema() method

Summary

This is a well-structured refactoring that moves from class-based to functional JSON Schema generation and adds instance methods. The architecture is solid overall.

Issues Found

2 Critical Bugs: Lines 72 & 88 in json-schema-processors.ts use "draft-4" instead of "draft-04", breaking draft-04 target handling
1 Bug: Line 195 incorrectly sets boolean literals as type: "string"
Several areas needing documentation: Custom override behavior, processor defaults, transform handling logic

Assessment

The refactoring improves modularity and adds useful functionality. Once the draft-04 bugs are fixed, this will be production-ready. The processor pattern is clean and maintainable.

All specific feedback has been posted as inline review comments.

^{｜ Triggered by Pullfrog ｜ Using Claude Code ｜ View workflow run ｜ pullfrog.com ｜ 𝕏}

colinhacks added 4 commits November 18, 2025 20:38

Checkpoint

d0c7184

Checkpoint

43b5705

Implement toJSONSchema method

86a740e

Implement Standard JSON Schema

1f35068

colinhacks assigned Copilot Nov 25, 2025

vercel bot deployed to Preview – zod-v4 November 25, 2025 06:11 View deployment

colinhacks added 4 commits November 24, 2025 22:37

Clean up

11d2071

Add back files

3e8ba43

Revert "Add back files"

34dc589

This reverts commit 3e8ba43.

Fix resolution bug

5e819dc

vercel bot deployed to Preview – zod-v4 November 25, 2025 07:35 View deployment

Tweak

a0b7ecd

vercel bot deployed to Preview – zod-v4 November 28, 2025 18:48 View deployment

Test

dda0ce9

Copilot AI review requested due to automatic review settings December 13, 2025 18:44

Copilot started reviewing on behalf of colinhacks December 13, 2025 18:44 View session

vercel bot had a problem deploying to Preview – zod-v4 December 13, 2025 18:45 Failure

Copilot AI reviewed Dec 13, 2025

View reviewed changes

Refactor files

2951000

vercel bot had a problem deploying to Preview – zod-v4 December 13, 2025 19:50 Failure

Address reviews

c9a5c55

vercel bot had a problem deploying to Preview – zod-v4 December 13, 2025 20:09 Failure

pullfrog bot reviewed Dec 13, 2025

View reviewed changes

Address pullfrog reviews

b3ed1a0

vercel bot had a problem deploying to Preview – zod-v4 December 13, 2025 20:22 Failure

colinhacks merged commit 767f320 into main Dec 13, 2025
4 of 5 checks passed

colinhacks deleted the json-schema-method branch December 13, 2025 20:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Add `.toJSONSchema()` method #5477

Add `.toJSONSchema()` method #5477

colinhacks commented Nov 25, 2025

colinhacks commented Nov 25, 2025

claude bot commented Nov 25, 2025 •

edited

Loading

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

colinhacks commented Dec 13, 2025

pullfrog bot left a comment •

edited

Loading

pullfrog bot Dec 13, 2025

pullfrog bot Dec 13, 2025

pullfrog bot Dec 13, 2025

pullfrog bot Dec 13, 2025

pullfrog bot Dec 13, 2025

pullfrog bot Dec 13, 2025

pullfrog bot Dec 13, 2025

pullfrog bot commented Dec 13, 2025

Uh oh!

Labels

2 participants

Uh oh!

Add .toJSONSchema() method #5477

Add .toJSONSchema() method #5477

Conversation

colinhacks commented Nov 25, 2025

colinhacks commented Nov 25, 2025

claude bot commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review: .toJSONSchema() Method Implementation

Architecture & Design ✅

Implementation Highlights ✅

Test Coverage ✅

Issues Found 🔍

1. Console.warn in old implementation (Minor)

2. Type safety concern (Minor)

3. Comment typo (Trivial)

4. Processor injection pattern (Design question)

5. Missing documentation

Performance Considerations ⚡

Code Quality ✅

Standard Schema Compliance ✅

Recommendations

Summary

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

colinhacks commented Dec 13, 2025

pullfrog bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

pullfrog bot Dec 13, 2025

Choose a reason for hiding this comment

pullfrog bot Dec 13, 2025

Choose a reason for hiding this comment

pullfrog bot Dec 13, 2025

Choose a reason for hiding this comment

pullfrog bot Dec 13, 2025

Choose a reason for hiding this comment

pullfrog bot Dec 13, 2025

Choose a reason for hiding this comment

pullfrog bot Dec 13, 2025

Choose a reason for hiding this comment

pullfrog bot Dec 13, 2025

Choose a reason for hiding this comment

pullfrog bot commented Dec 13, 2025

Review Complete

Summary

Issues Found

Assessment

Uh oh!

Labels

2 participants

Add `.toJSONSchema()` method #5477

Add `.toJSONSchema()` method #5477

claude bot commented Nov 25, 2025 •

edited

Loading

Code Review: `.toJSONSchema()` Method Implementation

pullfrog bot left a comment •

edited

Loading