Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

`Inline` fails on a recursive schema file shared through a response file: `reference ... not found in analysis phase`

Open
  • Is something wrong?
#285 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
55/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
go, openapi
Domain
backend-api-design

Research direction

Start by tracing openapi.Inline and the nested reference analysis for external response and schema files; the report does not name implementation or test files. Reproduce with the three operations and recursive Folder.yaml schema, then compare with two operations and a single-file document. Done when the three-operation case inlines successfully for OpenAPI 3.0.3 and 3.1.0, with the recursive reference targeting #/components/schemas/__Folder_yaml.

Written by the indexing model from the issue text.

Description

Summary

openapi.Inline (and openapi spec inline) fails when a self-referencing schema in its own file is reached through a response file that three or more operations reference. With two operations it inlines fine, and so does the same document written in one file.

Reproduction

openapi.yaml:

openapi: 3.0.3
info: {title: t, version: "1"}
paths:
  /f1:
    get:
      responses:
        "200": {$ref: ./responses/folder.yaml}
  /f2:
    get:
      responses:
        "200": {$ref: ./responses/folder.yaml}
  /f3:
    get:
      responses:
        "200": {$ref: ./responses/folder.yaml}

responses/folder.yaml:

description: ok
content: {application/json: {schema: {$ref: ../schemas/Folder.yaml}}}

schemas/Folder.yaml:

properties:
  parents:
    items: {$ref: ./Folder.yaml}

$ openapi spec inline openapi.yaml
Processing OpenAPI document: openapi.yaml
Error: failed to inline OpenAPI document: failed to inline references: failed to inline nested references in : failed to inline schemas: failed to inline schema: failed to inline schema: reference schemas/Folder.yaml#/components/schemas/__Folder_yaml not found in analysis phase

The library call (openapi.Unmarshal, then openapi.Inline with ResolveOptions{RootDocument: doc, TargetLocation: <absolute path>} and RemoveUnusedComponents: true) returns the same error.

Expected result

The document is inlined, as it is with /f3 removed: each response gets the Folder schema and the recursive ref points at #/components/schemas/__Folder_yaml. The same three operations also inline when they reference ./schemas/Folder.yaml directly, or when the response and the schema are in the root's components (one file).

Actual result

The error above, for openapi: 3.0.3 and 3.1.0 alike, and with four operations too. The reference it can't find, #/components/schemas/__Folder_yaml, is the name the inliner itself gives the recursive schema, here resolved against schemas/Folder.yaml.

Version

v1.26.0 (also main, d269643). CLI from go install github.com/speakeasy-api/openapi/cmd/openapi@latest (v0.0.0-20261016011534-d2696438ec74).

Dominant language
Go
Stars
276
Forks
21
Avg merge
1d 5h
Merged PRs (30d)
18

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from speakeasy-api/openapi

All issues in speakeasy-api/openapi

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.