Skip to content

openapi2conv: nil-guard components lookup in FromV3SchemaRef#1156

Merged
fenollp merged 2 commits intogetkin:masterfrom
SAY-5:fix/v3schemaref-nil-components-1062
Apr 25, 2026
Merged

openapi2conv: nil-guard components lookup in FromV3SchemaRef#1156
fenollp merged 2 commits intogetkin:masterfrom
SAY-5:fix/v3schemaref-nil-components-1062

Conversation

@SAY-5
Copy link
Copy Markdown
Contributor

@SAY-5 SAY-5 commented Apr 21, 2026

What

Fixes #1062.

FromV3SchemaRef indexes components.Schemas[name] whenever the input schema has a $ref. Several recursive call sites in this file (FromV3RequestBodyFormData most notably) already pass components=nil when descending into array items and nested refs, so hitting a $ref from that path nil-dereferenced the components argument and took down the whole V3→V2 conversion.

In practice this fires on real-world inputs like the OpenAI OpenAPI 3.0 spec, where CreateEmbeddingRequest references a sub-schema inside an array of formData items:

FromV3SchemaRef (openapi2_conv.go:851)
FromV3RequestBodyFormData (openapi2_conv.go:1028)
fromV3RequestBodies (openapi2_conv.go:799)

Fix

Guard the components lookup with a components != nil check. When the components table is not available we fall through to the same 'return the plain $ref' branch that already handles non-binary schema refs - semantically 'the target schema is not known locally, emit a pass-through ref' - instead of panicking. Runtime behaviour for callers that do pass a non-nil Components is unchanged.

Verification

Locally on macOS, go 1.26.2:

  • gofmt -s -l openapi2conv/openapi2_conv.go: clean
  • go vet ./...: clean
  • go test -race -count=1 ./openapi2conv/...: pass

Closes #1062

FromV3SchemaRef indexes components.Schemas[name] whenever the input
schema has a . Several recursive call sites in this file
(FromV3RequestBodyFormData among them) already pass components=nil
when descending into array items / nested refs, so hitting a ref
from that path nil-dereferenced and took down the whole V3→V2
conversion. In practice this fires on real-world inputs like the
OpenAI OpenAPI 3.0 spec, where CreateEmbeddingRequest references a
sub-schema inside an array of formData items (getkin#1062).

Guard the components lookup with a components != nil check. When
the components table is not available we fall through to the same
'return the plain ' branch that already handles non-binary
schema refs - semantically 'the target schema is not known locally,
emit a pass-through ref' - instead of panicking. Runtime behaviour
for callers that do pass a non-nil Components is unchanged.

Closes getkin#1062

Signed-off-by: SAY-5 <SAY-5@users.noreply.github.com>
Copy link
Copy Markdown
Collaborator

@fenollp fenollp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM but please add your spec (or a minified version of it) as a regression test.

Adds TestIssue1062_FormDataArrayOfRefDoesNotPanic with a minified
spec capturing the OpenAI OpenAPI 3 shape that triggered the original
report: a multipart/form-data request body whose property is an array
whose items are a $ref into #/components/schemas/.

Without the fix in this PR, the test panics inside FromV3 (line 723)
because FromV3RequestBodyFormData passes components=nil into
FromV3SchemaRef, which then nil-derefs on components.Schemas[name].
With the fix, the test passes and the resulting v2 spec contains the
expected formData parameter named 'documents'.

Signed-off-by: SAY-5 <say.apm35@gmail.com>
@SAY-5
Copy link
Copy Markdown
Contributor Author

SAY-5 commented Apr 25, 2026

@fenollp added TestIssue1062_FormDataArrayOfRefDoesNotPanic (openapi2conv/issue1062_test.go) — minified spec capturing the OpenAI shape: a multipart/form-data request body with an array property whose items $ref a component schema. Confirmed against the unfixed code (without this PR's nil-guard) it panics in FromV3 exactly as in the original stack frame; with the fix it converts cleanly and the resulting v2 spec carries the expected documents formData parameter.

@fenollp fenollp changed the title fix(openapi2conv): nil-guard components lookup in FromV3SchemaRef openapi2conv: nil-guard components lookup in FromV3SchemaRef Apr 25, 2026
@fenollp fenollp merged commit 3556929 into getkin:master Apr 25, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

nil pointer deference when converting OpenAI OpenAPI 3.0 spec to Swagger

2 participants