Bind OpenAPI 3.1 multi-type union parameters into any destinations

A parameter declared with a 3.1 multi-type union (type: [string, integer])
generates an `any` destination, which the binder rejected unconditionally:
"can not bind to destination of type: interface". The binder is
destination-driven, and an interface destination carries no information.

Add a Types field to BindStyledParameterOptions, BindQueryParameterOptions
and BindStringToObjectOptions carrying the union's member list. It is only
consulted when the destination is an empty interface, so concrete
destinations keep the reflection-driven path unchanged. The value binds to
the first member that parses, in specificity order (boolean, integer,
number, string) rather than declaration order: JSON Schema defines the type
array as an unordered set, and the always-succeeding string member would
otherwise shadow the rest. Numeric detection follows JSON number grammar,
so "007" and "+1" stay strings instead of being reinterpreted, and the
bound value matches what the same token would produce inside a JSON
document. Format applies only to its host member and only where it changes
decoding: int32/int64 and float/double select numeric widths, byte
base64-decodes the string member; annotation-only formats are ignored per
3.1 semantics. Non-scalar members and the "null" marker are skipped.

Closes #153

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: mromaszewicz

bindparam.go

@@ -80,6 +80,16 @@ type BindStyledParameterOptions struct {
 	// When set to "byte" and the destination is []byte, the value is
 	// base64-decoded rather than treated as a generic slice.
 	Format string
+	// Types is the OpenAPI 3.1 multi-type union member list of the parameter
+	// (e.g. ["string", "integer"]). A "null" entry — the 3.1 nullability
+	// marker, not a union member — is ignored, whether or not the generator
+	// already stripped it. When non-empty it takes precedence over
+	// Type. It is only consulted when the destination is an empty interface
+	// (`any`): the value binds to the first member that parses, trying
+	// boolean, integer, number, then string, with numeric detection
+	// following JSON number grammar. Concrete destinations ignore it and
+	// keep the reflection-driven behavior. See BindStringToObjectOptions.
+	Types []string
 	// AllowReserved, when true, indicates that the parameter value may
 	// contain RFC 3986 reserved characters without percent-encoding.
 	AllowReserved bool
@@ -193,7 +203,11 @@ func BindStyledParameterWithOptions(style string, paramName string, value string
 		}
 		value = parts[0]
 	}
-	return BindStringToObject(value, dest)
+	return BindStringToObjectWithOptions(value, dest, BindStringToObjectOptions{
+		Type:   opts.Type,
+		Format: opts.Format,
+		Types:  opts.Types,
+	})
 }
 
 // This is a complex set of operations, but each given parameter style can be
@@ -386,6 +400,16 @@ type BindQueryParameterOptions struct {
 	// When set to "byte" and the destination is []byte, the value is
 	// base64-decoded rather than treated as a generic slice.
 	Format string
+	// Types is the OpenAPI 3.1 multi-type union member list of the parameter
+	// (e.g. ["string", "integer"]). A "null" entry — the 3.1 nullability
+	// marker, not a union member — is ignored, whether or not the generator
+	// already stripped it. When non-empty it takes precedence over
+	// Type. It is only consulted when the destination is an empty interface
+	// (`any`): the value binds to the first member that parses, trying
+	// boolean, integer, number, then string, with numeric detection
+	// following JSON number grammar. Concrete destinations ignore it and
+	// keep the reflection-driven behavior. See BindStringToObjectOptions.
+	Types []string
 	// AllowReserved, when true, indicates that the parameter value may
 	// contain RFC 3986 reserved characters without percent-encoding.
 	AllowReserved bool
@@ -520,7 +544,11 @@ func BindQueryParameterWithOptions(style string, explode bool, required bool, pa
 						return nil
 					}
 				}
-				err = BindStringToObject(values[0], output)
+				err = BindStringToObjectWithOptions(values[0], output, BindStringToObjectOptions{
+					Type:   opts.Type,
+					Format: opts.Format,
+					Types:  opts.Types,
+				})
 			}
 			if err != nil {
 				return err
@@ -552,7 +580,11 @@ func BindQueryParameterWithOptions(style string, explode bool, required bool, pa
 			// is only meaningful for array and object types.
 			// See: https://swagger.io/docs/specification/serialization/
 			if k != reflect.Slice && k != reflect.Struct && k != reflect.Map {
-				err := BindStringToObject(values[0], output)
+				err := BindStringToObjectWithOptions(values[0], output, BindStringToObjectOptions{
+					Type:   opts.Type,
+					Format: opts.Format,
+					Types:  opts.Types,
+				})
 				if err != nil {
 					return err
 				}

bindstring.go

@@ -42,6 +42,19 @@ type BindStringToObjectOptions struct {
 	// When set to "byte" and the destination is []byte, the source string is
 	// base64-decoded rather than treated as a generic slice.
 	Format string
+	// Types is the OpenAPI 3.1 multi-type union member list of the parameter
+	// (e.g. ["string", "integer"]). A "null" entry — the 3.1 nullability
+	// marker, not a union member — is ignored, whether or not the generator
+	// already stripped it. When non-empty it takes precedence over
+	// Type. It is only consulted when the destination is an empty interface
+	// (`any`): the source string is bound to the first member that parses,
+	// trying boolean, integer, number, then string (most restrictive grammar
+	// first — the always-succeeding string member would otherwise shadow the
+	// rest). Numeric detection follows JSON number grammar, so the bound
+	// value matches what the same token would produce inside a JSON
+	// document. Concrete destinations ignore this field and keep the
+	// reflection-driven behavior.
+	Types []string
 }
 
 // BindStringToObjectWithOptions takes a string, and attempts to assign it to the destination
@@ -190,6 +203,22 @@ func BindStringToObjectWithOptions(src string, dst interface{}, opts BindStringT
 		// We fall through to the error case below if we haven't handled the
 		// destination type above.
 		fallthrough
+	case reflect.Interface:
+		// An interface destination normally can't be bound: there is no
+		// type information to parse with, so it falls to the error below.
+		// The exception is an empty interface (`any`) destination for a
+		// declared OpenAPI 3.1 multi-type union — opts.Types names the
+		// member types, and the value binds to the first member that
+		// parses. See bindStringToUnionMember for the exact semantics.
+		if t.Kind() == reflect.Interface && t.NumMethod() == 0 && len(opts.Types) > 0 {
+			bound, bindErr := bindStringToUnionMember(src, opts)
+			if bindErr != nil {
+				return fmt.Errorf("error binding string parameter: %w", bindErr)
+			}
+			v.Set(reflect.ValueOf(bound))
+			return nil
+		}
+		fallthrough
 	case reflect.Map:
 		// A bool-keyed map (such as nullable.Nullable[T], which is
 		// map[bool]T) is treated as a nullable wrapper: bind src into a

bindunion.go

@@ -0,0 +1,176 @@
+package runtime
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// unionMemberOrder is the order in which union member types are attempted
+// when binding a parameter value into an `any` destination: most restrictive
+// grammar first, so that the always-succeeding string member cannot shadow
+// the others. This is deliberately NOT the schema's declaration order — JSON
+// Schema defines the `type` array as an unordered set, so declaration order
+// carries no meaning, and any tool that normalizes a spec could otherwise
+// silently change binding behavior.
+var unionMemberOrder = []string{"boolean", "integer", "number", "string"}
+
+// bindStringToUnionMember binds src against the members of an OpenAPI 3.1
+// multi-type union (opts.Types), returning the value of the first member
+// that parses. Members are tried in unionMemberOrder, restricted to the
+// members actually present in opts.Types.
+//
+// Numeric detection uses JSON number grammar (RFC 8259), not strconv
+// leniency: "007", "+1" and " 1" are not JSON numbers, so they fall through
+// to the string member rather than being silently reinterpreted. The result
+// is the value the same token would produce inside a JSON document, which is
+// the documented mental model for multi-type unions bound into `any`.
+//
+// opts.Format applies only to the member it is defined for, and only where
+// it changes decoding: "int32"/"int64" select the integer width, "float"/
+// "double" the floating-point width, and "byte" base64-decodes the string
+// member into []byte. Annotation-only formats (date-time, uuid, ...) are
+// ignored — per OpenAPI 3.1 semantics `format` is an annotation and must not
+// reject a value, so parse failure cannot discriminate members. A format
+// whose host type is not present in opts.Types is inert.
+//
+// Non-scalar member names ("array", "object"), the "null" nullability marker
+// and unknown names are skipped: styled serialization of those into `any`
+// has no defined meaning. If no member parses, an error naming the union is
+// returned.
+func bindStringToUnionMember(src string, opts BindStringToObjectOptions) (any, error) {
+	members := make(map[string]bool, len(opts.Types))
+	for _, name := range opts.Types {
+		// The generator is expected to strip the "null" nullability marker
+		// before emitting Types, but the runtime and generator version
+		// independently, so don't rely on it — drop "null" here too.
+		// Nullability is not a union member: there is no null literal in
+		// styled parameter serialization to bind.
+		if name == "null" {
+			continue
+		}
+		members[name] = true
+	}
+
+	for _, name := range unionMemberOrder {
+		if !members[name] {
+			continue
+		}
+		switch name {
+		case "boolean":
+			// JSON grammar: exactly the lowercase literals, unlike
+			// strconv.ParseBool which also accepts "1", "t", "TRUE", etc.
+			if src == "true" {
+				return true, nil
+			}
+			if src == "false" {
+				return false, nil
+			}
+		case "integer":
+			if isJSONInteger(src) {
+				bits := 64
+				if opts.Format == "int32" {
+					bits = 32
+				}
+				if val, err := strconv.ParseInt(src, 10, bits); err == nil {
+					if bits == 32 {
+						return int32(val), nil
+					}
+					return val, nil
+				}
+				// Overflow: not representable as this member, fall
+				// through to the next one (number takes it as a float,
+				// string takes it verbatim).
+			}
+		case "number":
+			if isJSONNumber(src) {
+				bits := 64
+				if opts.Format == "float" {
+					bits = 32
+				}
+				if val, err := strconv.ParseFloat(src, bits); err == nil {
+					if bits == 32 {
+						return float32(val), nil
+					}
+					return val, nil
+				}
+				// Out of range for the width: fall through.
+			}
+		case "string":
+			if opts.Format == "byte" {
+				// Consistent with the concrete []byte destination: a
+				// declared base64 wire encoding that doesn't decode is an
+				// error, not a silent fallback to the raw string.
+				decoded, err := base64Decode(src)
+				if err != nil {
+					return nil, fmt.Errorf("error decoding base64 value '%s': %w", src, err)
+				}
+				return decoded, nil
+			}
+			return src, nil
+		}
+	}
+
+	return nil, fmt.Errorf("value '%s' does not match any member of type union %v", src, opts.Types)
+}
+
+// isJSONNumber reports whether s is a number under JSON grammar (RFC 8259):
+// an optional leading '-', an integer part with no leading zeros, and
+// optional fraction and exponent parts. No '+' sign, no whitespace, no hex.
+func isJSONNumber(s string) bool {
+	i := 0
+	if i < len(s) && s[i] == '-' {
+		i++
+	}
+	// Integer part: "0", or a nonzero digit followed by digits.
+	if i >= len(s) {
+		return false
+	}
+	switch {
+	case s[i] == '0':
+		i++
+	case s[i] >= '1' && s[i] <= '9':
+		i++
+		for i < len(s) && isDigit(s[i]) {
+			i++
+		}
+	default:
+		return false
+	}
+	// Fraction part.
+	if i < len(s) && s[i] == '.' {
+		i++
+		if i >= len(s) || !isDigit(s[i]) {
+			return false
+		}
+		for i < len(s) && isDigit(s[i]) {
+			i++
+		}
+	}
+	// Exponent part.
+	if i < len(s) && (s[i] == 'e' || s[i] == 'E') {
+		i++
+		if i < len(s) && (s[i] == '+' || s[i] == '-') {
+			i++
+		}
+		if i >= len(s) || !isDigit(s[i]) {
+			return false
+		}
+		for i < len(s) && isDigit(s[i]) {
+			i++
+		}
+	}
+	return i == len(s)
+}
+
+// isJSONInteger reports whether s is an integer token under JSON grammar: a
+// JSON number with no fraction or exponent part. This deliberately rejects
+// strconv leniencies like "007" or "+1", which would silently change the
+// value ("007" binds as the string "007", not the integer 7).
+func isJSONInteger(s string) bool {
+	return isJSONNumber(s) && !strings.ContainsAny(s, ".eE")
+}
+
+func isDigit(c byte) bool {
+	return c >= '0' && c <= '9'
+}