fix: resolve circular $ref in zod-to-json-schema for branded types#1766
Open
matantsach wants to merge 2 commits intoopenai:masterfrom
Open
fix: resolve circular $ref in zod-to-json-schema for branded types#1766matantsach wants to merge 2 commits intoopenai:masterfrom
matantsach wants to merge 2 commits intoopenai:masterfrom
Conversation
When a branded Zod type is reused across multiple fields, the generated JSON schema contains a self-referencing definition (e.g. a definition whose value is just a $ref back to itself). This happens because parseBrandedDef doesn't pass forceResolution through to parseDef when delegating to the inner type, so definition resolution hits refs.seen and creates a circular reference. Pass forceResolution through parseBrandedDef, matching the existing pattern in parseEffectsDef. Fixes openai#1739 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When a branded Zod type is reused across multiple fields, the generated JSON schema contains a self-referencing definition (e.g. a definition whose value is just a $ref back to itself). This happens because parseBrandedDef doesn't pass forceResolution through to parseDef when delegating to the inner type, so definition resolution hits refs.seen and creates a circular reference. Pass forceResolution through all transparent wrapper parsers (branded, catch, default, promise, readonly), matching the existing pattern in parseEffectsDef. Fixes openai#1739 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #1739
When a branded Zod type (e.g.
z.string().brand<"Id">()) is reused across multiple fields, the generated JSON schema contains a self-referencing definition — a definition whose value is just a$refback to itself. This makes the schema invalid and causes a crypticSyntaxError: Unexpected end of JSON inputwhen used withzodTextFormatorzodResponseFormat.Root Cause
parseBrandedDefdelegates toparseDeffor the inner type but doesn't pass through theforceResolutionparameter. When a definition is being force-resolved, the branded parser's inner call hitsrefs.seenand creates a$refback to the same definition path — producing the circular reference.The same structural issue exists in all transparent wrapper parsers (
catch,default,promise,readonly) that delegate toparseDefwithout forwardingforceResolution. OnlyparseEffectsDefwas already doing this correctly.Changes
forceResolutionthroughparseBrandedDef,parseCatchDef,parseDefaultDef,parsePromiseDef, andparseReadonlyDef— matching the existing pattern inparseEffectsDef$reffrom the issue (branded type reused in multiple fields)Testing
$refin definitions and that the branded type resolves to{type: "string"}z4.toJSONSchema()directly, not the vendored converter)