Skip to content

fix(json-schema): use $defs instead of definitions for openapi-3.0 target#5767

Open
mahmoodhamdi wants to merge 1 commit intocolinhacks:mainfrom
mahmoodhamdi:fix/to-json-schema-openapi-3-refs
Open

fix(json-schema): use $defs instead of definitions for openapi-3.0 target#5767
mahmoodhamdi wants to merge 1 commit intocolinhacks:mainfrom
mahmoodhamdi:fix/to-json-schema-openapi-3-refs

Conversation

@mahmoodhamdi
Copy link

What does this PR do?

Fixes toJSONSchema() with target: "openapi-3.0" to use $defs and #/$defs/ refs instead of definitions and #/definitions/ for recursive schemas.

Root cause

The defsSegment logic in to-json-schema.ts and json-schema-processors.ts used a binary choice: $defs for draft-2020-12, definitions for everything else. This meant openapi-3.0 was getting definitions — a Swagger 2.0 / JSON Schema Draft 4 concept that is not a recognized keyword in OpenAPI 3.0 Schema Objects.

For a recursive schema like:

const Recursive = z.lazy(() => z.object({ child: Recursive.optional() }));
const Schema = z.object({ data: Recursive });
z.toJSONSchema(Schema, { target: "openapi-3.0" });

The output contained "$ref": "#/definitions/__schema0" and a "definitions" key, which broke tools like Redoc that strictly validate against the OAS 3.0 spec.

Fix

Inverted the condition: definitions is now only used for draft-04 and draft-07, while everything else (including openapi-3.0 and draft-2020-12) uses $defs. This is forward-compatible since OpenAPI 3.1 adopted JSON Schema 2020-12's $defs convention.

Changed in three places:

  1. to-json-schema.ts line 250 — makeURI ref path segment
  2. to-json-schema.ts lines 486-491 — finalize defs key placement
  3. json-schema-processors.ts line 653 — registry toJSONSchema defs segment

Tests

Added a new test "recursive schema openapi-3.0 uses $defs" that verifies:

  • The output does NOT have a definitions key
  • The output DOES have a $defs key
  • Refs use #/$defs/ prefix
  • Full inline snapshot of expected output

All 3577 existing tests pass.

Related issue

Closes #5693

…rget

When using toJSONSchema() with target: "openapi-3.0" on recursive schemas,
the output contained #/definitions/ refs and a "definitions" key. This is
a Swagger 2.0 / JSON Schema Draft 4 convention not recognized by OpenAPI
3.0 Schema Objects, which broke tools like Redoc that strictly follow the
OAS 3.0 spec.

Changed the logic to use $defs and #/$defs/ for openapi-3.0 (same as
draft-2020-12), reserving "definitions" only for draft-04 and draft-07.
This is more forward-compatible since OAS 3.1 uses JSON Schema 2020-12.

Closes colinhacks#5693
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.

toJSONSchema with target "openapi-3.0" generates #/definitions/ refs for recursive schemas

1 participant