Code Generation Issue: Reference Resolution Breaking in JSON Schemas

[souvikinator]

Current Setup

1. Our schema structure:

schemas/
  |- constructs/
     |- v1beta1/
        |- model.json       # References core.json definitions
     |- openapi/
        |- models.yml    # Main OpenAPI schema file

2. Main OpenAPI schema (models.yml):

openapi: 3.0.0
components:
  schemas:
    model_definition:
      $ref: ../v1beta1/model.json

3. Model schema (model.json):

{
  "properties": {
    "id": {
      "$ref": "../core.json#/definitions/uuid"
    },
    // other properties...
  }
}

4. Core schema (core.json):

{
  "definitions": {
    "uuid": {
      "type": "string",
      "format": "uuid",
      "x-go-type": "uuid.UUID",
      "x-go-type-import": {
        "path": "github.com/gofrs/uuid"
      }
    }
  }
}

We're using a configuration file (config.yml) with import mappings to handle these references:

package: model
generate:
  models: true
import-mapping:
  "./core.yml": "github.com/[REDACTED]/schemas/models/core"
  "../core.json": "github.com/[REDACTED]/schemas/models/core"

Error Message

When running the code generation command:

oapi-codegen -config scripts/config.yml schemas/constructs/openapi/models.yml

We receive the following error:

error generating code: error generating type definitions: error generating Go types for component schemas: error converting Schema model_definition to Go type: error generating Go schema for property 'category': error generating Go schema for property 'id': error turning reference (../core.json#/definitions/uuid) into a Go type: unexpected reference depth: 3 for ref: #/definitions/uuid local: false

Expected Behavior

The code generator should successfully resolve external references across schema files and generate the appropriate Go code. Correct me if this is a wrong expectation.

Actual Behavior

The code generator fails to resolve the reference chain from models.yml → model.json → core.json, resulting in an error.

[sid6mathur]

@souvikinator did you manage a find the cause of this unexpected reference depth: 3 error? I am unable to shake this off with v2.4.1 no matter how much I simplify my JSON OpenAPI spec files. Is this something about JSON v/s YAML for the spec files? Thanks!

[moaddib666]

Hi @sid6mathur it's probably connected to your OpenAPI version the 2.0 has different format from 3.0 in case you use swaggo for generation of your docs you'd better switch to the v2.0.0-rc4 branch and add to swag init --v3.1