Invalid reference token: $defs
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 25.9k
- Forks
- 2.4k
- Avg merge
- 13h 10m
- Merged PRs (30d)
- 4
Description
Describe the bug
Im using Zod to generate my JSON Schema from my Typescript Types. I have some cycling dependencies (User has Groups, Group has Users, etc). For these Zod uses OpenAPI definitions.
Zod can use different targets for JSON Schemas, im currently using the default. https://zod.dev/json-schema?id=target - Targeting openapi-3.0 does not resolve this either, then we have a different issue.
Expected behavior
Redocly can use my spec.json.
Minimal reproducible OpenAPI snippet(if possible)
Screenshots
Additional context
I solved this until recently with dedicated Components and Manual Refs in the API Spec, but our new documentation engine cannot handle manual types currently.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by loading the attached spec.json and reviewing the OpenAPI and JSON Schema handling used when Redoc renders Zod-generated schemas with cyclic dependencies. Reproduce the invalid $defs reference, then add a regression test and verify that the specification renders without the reported error.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 46/100