Greptile Summary

This PR adds OpenAPI 3.1 multi-type union support by mapping unions to any and passing union member metadata to runtime parameter binders.

• Treats valid multi-type schemas as permissive Go aliases while preserving errors for malformed or OpenAPI 3.0 inputs.
• Avoids generating invalid constants for union schemas carrying enum or const.
• Extends OpenAPI 3.1 fixtures across schema, parameter, body, response, array, and composition positions.
• Regenerates framework outputs against runtime v1.7.0.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Reviews (2): Last reviewed commit: "Extend OpenAPI 3.1 union type binding to..." | Re-trigger Greptile

@mromaszewicz I'd expect that we'd treat this as a oneOf in this case?

You know, I'm not sure. This isn't like oneOf because that can handle any schema definition, however, this is much more limited, because it's just top level types. I do think any, like in this PR, is a better fit. If someone wants something that is [string, array, number], it's on them to disentangle what this is. any will have the json marshaler parse this as it sees fit, while if we make it something like json.RawMessage, then the user can decide how to parse it, so to me, it's a choice between any and json.RawMessage. I'm leaning towards any.

Thanks for the PR — the core mapping is well-guarded and the writeup is unusually thorough. We ran a deep analysis with Claude on this change (probing generated output for the interaction cases against a compiled runtime), and it surfaced a few issues that make the change incomplete as-is. Findings below, roughly in order of severity.

1. Parameter positions generate code that always fails at request time

A multi-type union in a parameter now generates successfully, but the endpoint is permanently broken:

parameters:
  - name: id
    in: path
    required: true
    schema:
      type: [string, integer]

The generated handler binds into an any destination, and runtime.BindStyledParameterWithOptions / BindQueryParameter unconditionally reject that:

error binding string parameter: can not bind to destination of type: interface

So a path param typed this way 400s on every request, and a query param 400s whenever it's supplied. Before this PR the spec failed loudly at generation time; after it, the failure moves to runtime. Unlike type: "null", a string-or-integer ID is a plausible real spec, and this is the one position where any isn't merely permissive but non-functional. We'd want parameter schemas to either keep erroring at generation, or bind the raw string — not silently generate a dead endpoint.

Relatedly, the PR body says generation is exercised across "property, additionalProperties, parameter, request body, response body, array items, and allOf positions", but the committed suite only covers property, additionalProperties, a named component, and the enum interaction. If you tested the other positions locally, could you commit those tests? The parameter case above is exactly the kind of thing that coverage would have caught.

2. type list + oneOf/anyOf siblings: the composition is silently discarded

UnionWithOneOf:
  type: [string, number]
  oneOf:
    - type: string
    - type: number

generates type UnionWithOneOf = any with no union accessors, because generateUnion only runs inside the object/typeless branch of GenerateGoSchema. Not a regression (this errored before), but it's a legal 3.1 conjunction that now silently loses the As…/From… machinery a bare oneOf gets. At minimum this deserves a line in the README note.

3. allOf ordering now swallows unions silently

AllOfUnionMember:
  allOf:
    - properties:
        name:
          type: string
    - type: [string, number]

generates a plain struct — the union member's type vanishes, because MergeSchemas does result.Type = s1.Type and discards s2's type when s1 has none. Reverse the member order and you get any with the properties dropped instead. The order-dependency is a pre-existing MergeSchemas bug (single types behave the same on main), so it's not this PR's fault — but the PR converts some of these from hard errors into silent, order-dependent output. Worth either a guard or a tracking issue.

Confirmed as fine

• The strict-server any-response compile failure reproduces on main with schema: {}, exactly as the PR body says — pre-existing, not introduced here.
• Nullability handling is correct throughout: [string, number, "null"] properties render bare any without omitempty, and nullable.Nullable[any] under the nullable-type option.
• The enum guard is correctly placed, the 3.0/typo rejection works as described, and x-go-type still wins as an escape hatch since extensions are handled before type dispatch.
• A union as a oneOf branch works (accessor typed any), with the caveat that As… can never fail, so branch discrimination degrades — same as typeless branches today.

Overall: the schema-position mapping looks merge-worthy, but we'd like the parameter story resolved (and the position tests committed) before this lands.

Update on the review findings above: the runtime side of finding 1 has shipped. runtime v1.7.0 adds a Types []string field to BindStyledParameterOptions / BindQueryParameterOptions, consulted only when the destination is an any: the value binds to the first union member that parses, in specificity order (boolean, integer, number, string) with JSON-grammar numeric detection, so union-typed parameters can now bind correctly instead of 400ing on every request.

What that leaves on the codegen side to complete the parameter story here:

1. Emit Types: []string{...} in the bind-option literals for multi-type union parameters — the bind call sites span the stdlib/echo/gin/fiber/iris templates.
2. Fix ParameterDefinition.SchemaType(), which emits the first entry of the type list (Type: "string" for [string, integer], and "null" for ["null", "string"]). Harmless while Type is unread, but wrong metadata to keep generating.
3. Bump the test modules' runtime dependency to v1.7.0 and add parameter positions to the openapi31 conformance suite with bind round-trips (the client side needs no runtime change — serialization reflects on the concrete value — but a round-trip test would pin both directions).

We're happy to either take these as a follow-up PR on our side, or you're welcome to fold them into this one — whichever you prefer. If you'd rather keep this PR at its current scope, we'll handle the plumbing after merge so both land in the same release.

On the remaining findings: having dug further, finding 2 (type list + oneOf/anyOf siblings) turns out to be mostly theoretical — in any coherent spec the sibling type list is redundant with the branch types (validators intersect; linters flag it), disagreement between them makes members unsatisfiable, and every such spec fails generation on main today anyway, so there's nobody to regress. We're treating it as a non-issue. Finding 3 (the MergeSchemas order dependency) is pre-existing and we'll take care of it, along with the strict-server any-response compile issue, on our side — none of that needs to block this PR.

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	github.com/​oapi-codegen/​runtime@​v1.5.0 ⏵ v1.7.0

View full report

Ok, @bendrucker , what do you think of this change. I added a commit which makes it much larger, since I had to change every template to pass through the OpenAPI 3.1 types array to the runtime package.

Just getting back to this, definitely didn't anticipate those edge cases, thanks for finishing this one for me! Will take a look back through and see if there are any follow ups, might tackle #2525 as well.

Revising my earlier comment: #2525 looks like the same bug as #1328, and #2514 already fixes it with the struct wrapper suggested in the issue. I reviewed that branch merged onto current main and verified it handles every shape from #2525, including the 3.1 unions from this PR. Details on the issue.