feat: replace oneOf/anyOf with json.RawMessage union + typed accessors

Replace the try-all-variants pointer-per-field union pattern with the
original oapi-codegen's proven json.RawMessage approach. Union types now
have a private 'union json.RawMessage' field with typed As/From/Merge
accessor methods for each variant.

Key changes:
- Union structs use json.RawMessage instead of pointer-per-variant
- Generate As<Variant>(), From<Variant>(), Merge<Variant>() for each member
- Add discriminator support: Discriminator() extracts the value from
  union data, ValueByDiscriminator() routes to the correct As method
- Discriminator mapping supports both explicit (spec mapping) and
  implicit (inferred from $ref schema names)
- Partial mappings handled gracefully (warn, don't error)
- Add JSONMerge helper (template + runtime) for Merge methods
- Use 'any' not 'interface{}' for ValueByDiscriminator return type

Generated code pattern:
  type Pet struct { union json.RawMessage }
  func (t Pet) AsCat() (Cat, error)
  func (t *Pet) FromCat(v Cat) error
  func (t *Pet) MergeCat(v Cat) error
  func (t Pet) Discriminator() (string, error)       // when present
  func (t Pet) ValueByDiscriminator() (any, error)    // when mapped

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mromaszewicz

experimental/codegen/internal/codegen.go

@@ -413,6 +413,9 @@ func generateHelper(name string, ctx *CodegenContext) (string, error) {
 	case "marshal_form":
 		ctx.AddTemplateImports(templates.MarshalFormHelperTemplate.Imports)
 		return generateMarshalFormHelper()
+	case "json_merge":
+		ctx.AddTemplateImports(templates.JSONMergeHelperTemplate.Imports)
+		return generateJSONMergeHelper()
 	default:
 		return "", fmt.Errorf("unknown helper: %s", name)
 	}
@@ -439,6 +442,27 @@ func generateMarshalFormHelper() (string, error) {
 	return result.String(), nil
 }
 
+// generateJSONMergeHelper generates the JSONMerge helper function.
+func generateJSONMergeHelper() (string, error) {
+	tmplInfo := templates.JSONMergeHelperTemplate
+	content, err := templates.TemplateFS.ReadFile("files/" + tmplInfo.Template)
+	if err != nil {
+		return "", fmt.Errorf("reading json merge helper template: %w", err)
+	}
+
+	tmpl, err := template.New(tmplInfo.Name).Parse(string(content))
+	if err != nil {
+		return "", fmt.Errorf("parsing json merge helper template: %w", err)
+	}
+
+	var result strings.Builder
+	if err := tmpl.Execute(&result, nil); err != nil {
+		return "", fmt.Errorf("executing json merge helper template: %w", err)
+	}
+
+	return result.String(), nil
+}
+
 // generateParamFunctionsFromContext generates the parameter styling/binding functions based on CodegenContext usage.
 // typesPrefix is prepended to Date/DateFormat references in param templates; empty when embedded.
 func generateParamFunctionsFromContext(ctx *CodegenContext, typesPrefix string) (string, error) {
@@ -1012,17 +1036,29 @@ func generateAnyOfType(gen *TypeGenerator, desc *SchemaDescriptor) string {
 		return ""
 	}
 
-	// anyOf types only need encoding/json (not fmt like oneOf)
-	gen.AddJSONImport()
-
-	doc := extractDescription(desc.Schema)
-	code := GenerateUnionType(desc.ShortName, members, false, doc)
+	gen.AddJSONImports()
 
-	marshalCode := GenerateUnionMarshalAnyOf(desc.ShortName, members)
-	unmarshalCode := GenerateUnionUnmarshalAnyOf(desc.ShortName, members)
-	applyDefaultsCode := GenerateUnionApplyDefaults(desc.ShortName, members)
+	cfg := UnionTypeConfig{
+		TypeName:      desc.ShortName,
+		Members:       members,
+		IsOneOf:       false,
+		Doc:           extractDescription(desc.Schema),
+		Discriminator: desc.Discriminator,
+		HelperPrefix:  gen.helperPrefix(),
+	}
 
-	code += "\n" + marshalCode + "\n" + unmarshalCode + "\n" + applyDefaultsCode
+	code := GenerateUnionType(cfg)
+	code += "\n" + GenerateUnionAccessors(cfg)
+	if discCode := GenerateUnionDiscriminator(cfg); discCode != "" {
+		gen.AddImport("errors")
+		code += "\n" + discCode
+	}
+	code += "\n" + GenerateUnionMarshalUnmarshal(cfg)
+	if len(cfg.FixedFields) > 0 {
+		gen.AddImport("fmt")
+	}
+	gen.NeedHelper("json_merge")
+	code += "\n" + GenerateUnionApplyDefaults(desc.ShortName)
 
 	return code
 }
@@ -1034,17 +1070,29 @@ func generateOneOfType(gen *TypeGenerator, desc *SchemaDescriptor) string {
 		return ""
 	}
 
-	// Union types need encoding/json and fmt for marshal/unmarshal
 	gen.AddJSONImports()
 
-	doc := extractDescription(desc.Schema)
-	code := GenerateUnionType(desc.ShortName, members, true, doc)
-
-	marshalCode := GenerateUnionMarshalOneOf(desc.ShortName, members)
-	unmarshalCode := GenerateUnionUnmarshalOneOf(desc.ShortName, members)
-	applyDefaultsCode := GenerateUnionApplyDefaults(desc.ShortName, members)
+	cfg := UnionTypeConfig{
+		TypeName:      desc.ShortName,
+		Members:       members,
+		IsOneOf:       true,
+		Doc:           extractDescription(desc.Schema),
+		Discriminator: desc.Discriminator,
+		HelperPrefix:  gen.helperPrefix(),
+	}
 
-	code += "\n" + marshalCode + "\n" + unmarshalCode + "\n" + applyDefaultsCode
+	code := GenerateUnionType(cfg)
+	code += "\n" + GenerateUnionAccessors(cfg)
+	if discCode := GenerateUnionDiscriminator(cfg); discCode != "" {
+		gen.AddImport("errors")
+		code += "\n" + discCode
+	}
+	code += "\n" + GenerateUnionMarshalUnmarshal(cfg)
+	if len(cfg.FixedFields) > 0 {
+		gen.AddImport("fmt")
+	}
+	gen.NeedHelper("json_merge")
+	code += "\n" + GenerateUnionApplyDefaults(desc.ShortName)
 
 	return code
 }
@@ -1095,17 +1143,27 @@ func collectUnionMembers(gen *TypeGenerator, parentDesc *SchemaDescriptor, membe
 		}
 	}
 
+	// Build reverse mapping: $ref path → []discriminator values
+	refToDiscValues := make(map[string][]string)
+	if parentDesc != nil && parentDesc.Discriminator != nil {
+		for discValue, refPath := range parentDesc.Discriminator.Mapping {
+			refToDiscValues[refPath] = append(refToDiscValues[refPath], discValue)
+		}
+	}
+
 	for i, proxy := range memberProxies {
 		var memberType string
-		var fieldName string
+		var methodName string
 		var hasApplyDefaults bool
+		var discValues []string
 
 		if proxy.IsReference() {
 			ref := proxy.GetReference()
 			if target, ok := gen.schemaIndex[ref]; ok {
 				memberType = target.ShortName
-				fieldName = target.ShortName
+				methodName = target.ShortName
 				hasApplyDefaults = schemaHasApplyDefaults(target.Schema)
+				discValues = refToDiscValues[ref]
 			} else {
 				continue
 			}
@@ -1124,23 +1182,23 @@ func collectUnionMembers(gen *TypeGenerator, parentDesc *SchemaDescriptor, membe
 
 			if desc, ok := descByPath[memberPath.String()]; ok && desc.ShortName != "" {
 				memberType = desc.ShortName
-				fieldName = desc.ShortName
+				methodName = desc.ShortName
 				hasApplyDefaults = schemaHasApplyDefaults(desc.Schema)
 			} else {
 				// This is a primitive type that doesn't have a named type
 				goType := gen.goTypeForSchema(schema, nil)
 				memberType = goType
-				// Create a field name based on the type
-				fieldName = gen.converter.ToTypeName(goType) + fmt.Sprintf("%d", i)
+				methodName = gen.converter.ToTypeName(goType) + fmt.Sprintf("%d", i)
 				hasApplyDefaults = false // Primitive types don't have ApplyDefaults
 			}
 		}
 
 		members = append(members, UnionMember{
-			FieldName:        fieldName,
-			TypeName:         memberType,
-			Index:            i,
-			HasApplyDefaults: hasApplyDefaults,
+			TypeName:            memberType,
+			MethodName:          methodName,
+			Index:               i,
+			HasApplyDefaults:    hasApplyDefaults,
+			DiscriminatorValues: discValues,
 		})
 	}
 

experimental/codegen/internal/gather.go

@@ -3,6 +3,7 @@ package codegen
 import (
 	"fmt"
 	"log/slog"
+	"strings"
 
 	"github.com/pb33f/libopenapi/datamodel/high/base"
 	v3 "github.com/pb33f/libopenapi/datamodel/high/v3"
@@ -619,6 +620,42 @@ func (g *gatherer) gatherFromSchema(schema *base.Schema, basePath SchemaPath, pa
 		}
 	}
 
+	// Extract discriminator information for oneOf/anyOf schemas
+	if parent != nil && schema.Discriminator != nil && schema.Discriminator.PropertyName != "" {
+		disc := schema.Discriminator
+		info := &DiscriminatorInfo{
+			PropertyName: disc.PropertyName,
+			Mapping:      make(map[string]string),
+		}
+
+		if disc.Mapping != nil && disc.Mapping.Len() > 0 {
+			// Explicit mapping from spec
+			info.IsExplicit = true
+			for pair := disc.Mapping.First(); pair != nil; pair = pair.Next() {
+				info.Mapping[pair.Key()] = pair.Value()
+			}
+		} else {
+			// Implicit mapping: infer from $ref schema names
+			info.IsExplicit = false
+			members := schema.OneOf
+			if len(members) == 0 {
+				members = schema.AnyOf
+			}
+			for _, proxy := range members {
+				if proxy.IsReference() {
+					ref := proxy.GetReference()
+					parts := strings.Split(ref, "/")
+					if len(parts) > 0 {
+						schemaName := parts[len(parts)-1]
+						info.Mapping[schemaName] = ref
+					}
+				}
+			}
+		}
+
+		parent.Discriminator = info
+	}
+
 	// AdditionalProperties (if it's a schema, not a boolean)
 	if schema.AdditionalProperties != nil && schema.AdditionalProperties.A != nil {
 		addPropsPath := basePath.Append("additionalProperties")