experimental: handle oneOf/anyOf nullable $ref pattern as Nullable[T]

Closes #19

Detect the OpenAPI 3.1 nullable $ref pattern — oneOf/anyOf with a $ref
and {type: "null"} — and generate Nullable[T] instead of a union struct.
This is the standard way to express nullable referenced types in 3.1
since $ref cannot be combined with type arrays.

Skip gathering inline nullable aggregate schemas during the schema
collection phase, eliminating unnecessary type aliases like
NullableRefOneOfNullableObject that were generated alongside the
correct Nullable[T] struct fields.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mromaszewicz

experimental/codegen/internal/gather.go

@@ -376,14 +376,17 @@ func (g *gatherer) gatherFromSchemaProxy(proxy *base.SchemaProxy, path SchemaPat
 	// References are always gathered (they point to real schemas)
 	// Simple types (primitives without enum) are skipped for inline schemas
 	// Inline nullable primitives (under properties/) don't need types - they use Nullable[T] directly
+	// Inline nullable aggregates (oneOf/anyOf: [$ref, {type: null}]) also use Nullable[T] directly
 	// Schemas with type-override or type-name-override extensions always need types
 	// Component schemas (components/schemas/*) always get a type alias, even for primitives,
 	// so that external packages can reference them by name.
 	isComponentSchema := len(path) == 3 && path[0] == "components" && path[1] == "schemas"
 	isInlineProperty := path.ContainsProperties()
 	skipInlineNullablePrimitive := isInlineProperty && isNullablePrimitive(schema)
+	isNullableAgg, _ := isNullableAggregate(schema)
+	skipInlineNullableAggregate := isInlineProperty && isNullableAgg
 	needsType := isRef || needsGeneratedType(schema) || hasTypeOverride || hasTypeNameOverride || isComponentSchema
-	if needsType && !skipInlineNullablePrimitive {
+	if needsType && !skipInlineNullablePrimitive && !skipInlineNullableAggregate {
 		desc := &SchemaDescriptor{
 			Path:        path,
 			Parent:      parent,
@@ -525,6 +528,33 @@ func needsGeneratedType(schema *base.Schema) bool {
 	return false
 }
 
+// isNullableAggregate detects the OpenAPI 3.1 pattern for nullable $ref types:
+// oneOf/anyOf with exactly two members where one is {type: "null"}.
+// Since you cannot combine $ref with a type array, this is the standard way to
+// make a referenced type nullable. Returns the non-null member's schema proxy
+// if matched.
+func isNullableAggregate(schema *base.Schema) (bool, *base.SchemaProxy) {
+	if schema == nil {
+		return false, nil
+	}
+
+	var members []*base.SchemaProxy
+	if len(schema.OneOf) == 2 {
+		members = schema.OneOf
+	} else if len(schema.AnyOf) == 2 {
+		members = schema.AnyOf
+	} else {
+		return false, nil
+	}
+
+	if s := members[0].Schema(); s != nil && len(s.Type) == 1 && s.Type[0] == "null" {
+		return true, members[1]
+	} else if s := members[1].Schema(); s != nil && len(s.Type) == 1 && s.Type[0] == "null" {
+		return true, members[0]
+	}
+	return false, nil
+}
+
 // isNullablePrimitive returns true if the schema is a nullable primitive type.
 // Nullable primitives need Nullable[T] wrapper types.
 func isNullablePrimitive(schema *base.Schema) bool {

experimental/codegen/internal/test/comprehensive/output/comprehensive.gen.go

@@ -0,0 +1,42 @@
+package output
+
+import "testing"
+
+// TestNullableRefOneOf verifies that oneOf: [$ref, {type: "null"}] generates
+// Nullable[T] instead of a full union struct. This is the standard OpenAPI 3.1
+// pattern for making a $ref'd type nullable.
+// https://github.com/oapi-codegen/oapi-codegen-exp/issues/19
+func TestNullableRefOneOf(t *testing.T) {
+	obj := NullableRefOneOf{
+		NullableObject: NewNullableWithValue(SimpleObject{ID: 1}),
+	}
+	val := obj.NullableObject.MustGet()
+	if val.ID != 1 {
+		t.Errorf("NullableObject.ID = %d, want 1", val.ID)
+	}
+
+	// Test null state
+	obj.NullableObject.SetNull()
+	if !obj.NullableObject.IsNull() {
+		t.Error("NullableObject should be null after SetNull()")
+	}
+
+	// Optional nullable ref should also be Nullable[T] (not *Nullable[T]),
+	// because Nullable already handles the "unspecified" state.
+	obj2 := NullableRefOneOf{
+		NullableObject:         NewNullableWithValue(SimpleObject{ID: 2}),
+		NullableObjectOptional: NewNullableWithValue(SimpleObject{ID: 3}),
+	}
+	_ = obj2
+}
+
+// TestNullableRefAnyOf verifies the same pattern using anyOf instead of oneOf.
+func TestNullableRefAnyOf(t *testing.T) {
+	obj := NullableRefAnyOf{
+		NullableObject: NewNullableWithValue(SimpleObject{ID: 1}),
+	}
+	val := obj.NullableObject.MustGet()
+	if val.ID != 1 {
+		t.Errorf("NullableObject.ID = %d, want 1", val.ID)
+	}
+}

experimental/codegen/internal/test/comprehensive/output/comprehensive_test.go

@@ -278,6 +278,32 @@ components:
             - integer
             - "null"
 
+    # OpenAPI 3.1 nullable $ref via oneOf/anyOf — the only way to make
+    # a referenced type nullable since you cannot combine $ref with type arrays.
+    NullableRefOneOf:
+      type: object
+      required:
+        - nullableObject
+      properties:
+        nullableObject:
+          oneOf:
+            - $ref: "#/components/schemas/SimpleObject"
+            - type: "null"
+        nullableObjectOptional:
+          oneOf:
+            - $ref: "#/components/schemas/SimpleObject"
+            - type: "null"
+
+    NullableRefAnyOf:
+      type: object
+      required:
+        - nullableObject
+      properties:
+        nullableObject:
+          anyOf:
+            - $ref: "#/components/schemas/SimpleObject"
+            - type: "null"
+
     # ===========================================
     # ARRAYS
     # ===========================================

experimental/codegen/internal/test/files/comprehensive.yaml

@@ -242,6 +242,19 @@ func (g *TypeGenerator) goTypeForSchema(schema *base.Schema, desc *SchemaDescrip
 	if len(schema.AllOf) > 0 {
 		return g.allOfType(desc)
 	}
+
+	// Check for nullable oneOf/anyOf pattern: [realType, {type: "null"}]
+	// This is the OpenAPI 3.1 way to make a $ref'd type nullable.
+	if ok, nonNullProxy := isNullableAggregate(schema); ok {
+		if baseType := g.resolveNullableOneOfType(nonNullProxy); baseType != "" {
+			if g.ctx.RuntimeTypesPrefix() != "" {
+				return g.ctx.RuntimeTypesPrefix() + "Nullable[" + baseType + "]"
+			}
+			g.AddNullableTemplate()
+			return "Nullable[" + baseType + "]"
+		}
+	}
+
 	if len(schema.AnyOf) > 0 {
 		return g.anyOfType(desc)
 	}
@@ -462,6 +475,20 @@ func (g *TypeGenerator) oneOfType(desc *SchemaDescriptor) string {
 	return "any"
 }
 
+// resolveNullableOneOfType resolves the Go type for the non-null member of a
+// nullable oneOf/anyOf pattern. Returns empty string if it can't be resolved.
+func (g *TypeGenerator) resolveNullableOneOfType(nonNullProxy *base.SchemaProxy) string {
+	if nonNullProxy.IsReference() {
+		ref := nonNullProxy.GetReference()
+		if target, ok := g.schemaIndex[ref]; ok {
+			return target.ShortName
+		}
+		return ""
+	}
+	// Inline non-null member — resolve its type directly
+	return g.goTypeForSchema(nonNullProxy.Schema(), nil)
+}
+
 // StructField represents a field in a generated Go struct.
 type StructField struct {
 	Name            string // Go field name
@@ -923,6 +950,12 @@ func GetSchemaKind(desc *SchemaDescriptor) SchemaKind {
 	if len(schema.AllOf) > 0 {
 		return KindAllOf
 	}
+
+	// Nullable oneOf/anyOf pattern: [{$ref/type}, {type: "null"}] → alias to Nullable[T]
+	if ok, _ := isNullableAggregate(schema); ok {
+		return KindAlias
+	}
+
 	if len(schema.AnyOf) > 0 {
 		return KindAnyOf
 	}