Support for internal refs when generating JSON schemas

[aringeri]

Description

Hi,
My overall goal is to use hey-api/openapi-ts in combination react-jsonschema-form.

I would like to generate react forms from component schemas found in an OpenAPI spec:

OpenAPI.json ->  JSON Schema (@hey-api/schemas) -> React Form (react-jsonschema-form)

While this works well for simple components, I find it falls down when a component schema references another component in the same OpenAPI spec.

For example this OpenAPI spec, the January definition has a $ref to Answer (example taken from this repo):

openapi: 3.0.3
info:
  title: title
  description: description
  version: 1.0.0
components:
  schemas:
    January:
      description: January description
      type: object
      required:
        - isJanuary
      properties:
        isJanuary:
          description: isJanuary description
          $ref: '#/components/schemas/Answer'
        isFebruary:
          description: isFebruary description
          $ref: '#/components/schemas/Answer'
    Answer:
      type: string
      nullable: true
      enum:
        - yes
        - no

hey-api/openapi-ts generates the following schemas.gen.ts file:

// This file is auto-generated by @hey-api/openapi-ts

export const Answer = {
  type: "string",
  nullable: true,
  enum: ["yes", "no"],
} as const;


export const January = {
  description: "January description",
  type: "object",
  required: ["isJanuary"],
  properties: {
    isJanuary: {
      description: "isJanuary description",
      $ref: "#/components/schemas/Answer",
    },
    isFebruary: {
      description: "isFebruary description",
      $ref: "#/components/schemas/Answer",
    },
  },
} as const;

If I try to pass the January schema to a react-jsonschema-form Form, it fails because it cannot find the reference "#/components/schemas/Answer":

import Form from '@rjsf/core';
import validator from '@rjsf/validator-ajv8';
import { January } from "@/schemas.gen.ts";

...

// Fails with 'Could not find a definition for #/components/schemas/Answer.'
<Form
   schema={January}
   validator={validator}
/>

A current workaround is to attach the referenced types in the schema given to the form, but this is not scalable for larger/complex schemas.
(We would hopefully not have to manually do this for each schema)

const schema = {
    components: {
       schemas: {
         Answer: Answer
       }
    },
    ...January
}

Can you suggest any ways forward?
I would essentially want each JSON schema to be self-contained and pull in any required references.

Potentially references could be resolved in the generated typescript (assuming no self/circular references):

export const Answer = {
  type: "string",
  nullable: true,
  enum: ["yes", "no"],
} as const;


export const January = {
  description: "January description",
  type: "object",
  required: ["isJanuary"],
  properties: {
    isJanuary: {
      description: "isJanuary description",
      ...Answer
    },
    isFebruary: {
      description: "isFebruary description",
      ...Answer
    },
  },
} as const;

[dosubot]

Hi @aringeri! I'm Dosu and I’m helping the openapi-ts team.

There isn't built-in support in hey-api/openapi-ts for automatically inlining or resolving $ref references to make schemas fully self-contained. The generated schemas use $ref for internal references, and react-jsonschema-form does not resolve these automatically, which leads to the issue you're seeing. While you can use custom patches in hey-api/openapi-ts to manually modify schemas, this approach doesn't scale for complex or deeply nested references and isn't automated for $ref inlining reference.

A common solution is to post-process your generated schemas using an external tool like json-schema-ref-parser or json-schema-deref. These tools can dereference (inline) all $ref references, producing a self-contained schema object that react-jsonschema-form can consume. This approach is widely used in the ecosystem and works well as long as your schemas don't have circular references (which most deref tools can detect and warn about).

Typical workflow:

1. Generate your schemas as usual with hey-api/openapi-ts.
2. Use a tool like json-schema-ref-parser in a build step or script to dereference the schema you want to use with react-jsonschema-form.
3. Pass the resulting self-contained schema to your form.

Example with json-schema-ref-parser:

const $RefParser = require('json-schema-ref-parser');
const schema = require('./schemas.gen.js').January;

$RefParser.dereference(schema, (err, dereferencedSchema) => {
  if (err) throw err;
  // dereferencedSchema is now self-contained
});

This avoids manual patching and scales to complex schemas. If you need to handle circular references, check the tool's documentation for options or warnings.

Let me know if you want a more detailed example or have questions about integrating this into your workflow!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[mrlubos]

What would be the solution for circular references?

[aringeri]

My use-case does not include circular references so I would be open to feedback on how to approach it.

My initial thought would be to not support circular references (detect them and fail), and make the new 'inlining/dereferencing' configurable in the schemas plugin.

I might try to pre-process the OpenAPI spec and inline the references (similar to the suggestion above by dosubot).

This library has put some thought into circular references although will generate code with circular imports (which I believe won't run): https://github.com/toomuchdesign/openapi-ts-json-schema?tab=readme-ov-file#refs-handling