Exception is thrown if a $ref points to an other file

[erosb]

Hello,

First of all, thank you for all your work put into this project.

I tried to use fabrikt to generate code from an openapi yaml which has $refs pointing to external files.

Reproducer:

minimal-api.yaml:

openapi: "3.1.0"
info:
  title: Partners API
  version: "1.0"
paths:
  /api/dummy:
    post:
      operationId: createDummy
      requestBody:
        content:
          application/json:
            schema:
              $ref: "./dummy/DummyCreationRequest.yaml"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "./dummy/Dummy.yaml"
          description: OK

dummy/DummyCreationRequest.yaml:

$schema: https://json-schema.org/draft/2020-12/schema
type: object
additionalProperties: false
properties:
  name:
    type: string
    minLength: 4
    maxLength: 30

dummy/Dummy.yaml:

$schema: https://json-schema.org/draft/2020-12/schema
type: object
additionalProperties: false
properties:
  id:
    type: integer
  name:
    type: string
    minLength: 4
    maxLength: 30

The command was:

java -jar ./fabrikt/build/libs/fabrikt*.jar \
  --output-directory 'src/main/kotlin' \
  --base-package 'com.example' \
  --api-file './minimal-api.yaml' \
  --targets 'controllers' \
  --validation-library javax_validation

And finally, the exception:

Nov 02, 2025 7:29:12 PM com.cjbooms.fabrikt.cli.CodeGen generate
INFO: Generating code and dumping to src/main/kotlin/
Exception in thread "main" java.lang.IllegalArgumentException: simpleNames must not contain empty items: []
	at com.squareup.kotlinpoet.ClassName.<init>(ClassName.kt:58)
	at com.cjbooms.fabrikt.generators.model.ModelGenerator$Companion.generatedType(ModelGenerator.kt:170)
	at com.cjbooms.fabrikt.generators.model.ModelGenerator$Companion.toClassName(ModelGenerator.kt:162)
	at com.cjbooms.fabrikt.generators.model.ModelGenerator$Companion.toModelType(ModelGenerator.kt:90)
	at com.cjbooms.fabrikt.generators.model.ModelGenerator$Companion.toModelType$default(ModelGenerator.kt:84)
	at com.cjbooms.fabrikt.generators.controller.ControllerGeneratorUtils.happyPathResponse(ControllerGeneratorUtils.kt:27)
	at com.cjbooms.fabrikt.generators.controller.SpringControllerInterfaceGenerator.buildFunction(SpringControllerInterfaceGenerator.kt:71)
	at com.cjbooms.fabrikt.generators.controller.AnnotationBasedControllerInterfaceGenerator.buildController(AnnotationBasedControllerInterfaceGenerator.kt:36)
	at com.cjbooms.fabrikt.generators.controller.SpringControllerInterfaceGenerator.generate(SpringControllerInterfaceGenerator.kt:50)
	at com.cjbooms.fabrikt.generators.controller.SpringControllerInterfaceGenerator.generate(SpringControllerInterfaceGenerator.kt:36)
	at com.cjbooms.fabrikt.cli.CodeGenerator.controllers(CodeGenerator.kt:98)
	at com.cjbooms.fabrikt.cli.CodeGenerator.generateControllerInterfaces(CodeGenerator.kt:47)
	at com.cjbooms.fabrikt.cli.CodeGenerator.generateCode(CodeGenerator.kt:39)
	at com.cjbooms.fabrikt.cli.CodeGenerator.generate(CodeGenerator.kt:34)
	at com.cjbooms.fabrikt.cli.CodeGen.generate(CodeGen.kt:65)
	at com.cjbooms.fabrikt.cli.CodeGen.main(CodeGen.kt:38)

The rest of the tooling we use for openapi has no problems with recognizing such schemas, so I think in theory this should work with fabrikt as well.

[ulrikandersen]

Hi @erosb,

Thanks for your report. Fabrikt does support resolving external schemas, so something in your file structure differs from what Fabrikt supports.

My best guess is that Fabrikt is unable to determine names for the schemas. It needs the names in order to be able to generate the models.

This minimal-api.yaml generates the expected models & controller. Here Fabrikt is able to determine the names from the components.schemas.

openapi: "3.1.0"
info:
  title: Partners API
  version: "1.0"
paths:
  /api/dummy:
    post:
      operationId: createDummy
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DummyCreationRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dummy"
          description: OK
components:
  schemas:
    DummyCreationRequest:
      $ref: "./dummy/DummyCreationRequest.yaml"
    Dummy:
      $ref: "./dummy/Dummy.yaml"

[ulrikandersen]

Tip: If you are unable to change the source schema you can apply bundling to the OpenAPI files before feeding them into Fabrikt.

Using redocly-cli:

redocly bundle minimal-api.yaml -o minimal-api-bundle.yaml

This results in an OpenAPI file compatible with Fabrikt:

openapi: 3.1.0
info:
  title: Partners API
  version: '1.0'
paths:
  /api/dummy:
    post:
      operationId: createDummy
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DummyCreationRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dummy'
          description: OK
components:
  schemas:
    DummyCreationRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 4
          maxLength: 30
    Dummy:
      type: object
      additionalProperties: false
      properties:
        id:
          type: integer
        name:
          type: string
          minLength: 4
          maxLength: 30

[erosb]

Hello, thanks for the suggestion. Yes, using redocly-cli for bundling can be a workaround. I think it would be more robust if fabrikt would have a naming strategy for schemas at arbitrary locations. Even if it is a nontrivial problem, since json schemas don't have any natural names.

By the way, I've seen that the json schema parser under fabrikt is still a draft-04 json schema parser. Are there any plans to migrate to a more modern schema representation?

[ulrikandersen]

I think it would be more robust if fabrikt would have a naming strategy for schemas at arbitrary locations.

That would indeed be a really nice addition to Fabrikt! Could also solve some of the limitations that currently exist for inlined schemas. Contributions are welcome 🤗

By the way, I've seen that the json schema parser under fabrikt is still a draft-04 json schema parser. Are there any plans to migrate to a more modern schema representation?

AFAIK there's no active plans to replace the KaiZen-OpenApi-Parser. Support for OpenAPI 3.1 features have so far been added on a per request basis.