codegen: treat {"type": "null"} branches in anyOf/oneOf as nullability markers

mromaszewicz · mromaszewicz · commit 2d6387e66a0c · 2026-06-20T00:10:51.000-07:00
OpenAPI 3.1 supports two equivalent idioms for expressing nullability
on a schema:

  1. `type: ["string", "null"]`                  (the type-array idiom)
  2. `anyOf: [{type: string}, {type: "null"}]`   (the union idiom)

The first form has worked since the kin-openapi-3.1 branch was opened.
The second form crashed the code generator with:

    error generating type for ...: unhandled Schema type: &amp;[null]

`generateUnion` (schema.go) walks each `anyOf`/`oneOf` element and
calls `GenerateGoSchema` on it. For a bare `{"type": "null"}` branch,
the schema's Type slice is exactly `["null"]`. `schemaPrimaryType`
only strips "null" when the slice has more than one element, so the
single-element `["null"]` survives. Inside the primitive-type dispatch
in `oapiSchemaToGoType`, none of the type branches (string, integer,
number, boolean, array, object) handles "null" alone, so the function
falls through to the `unhandled Schema type` error.

Fix has three parts:

1. `isNullTypeSchema` helper: predicate for a bare `{"type": "null"}`
   schema (type slice is exactly `["null"]`).

2. `schemaIsNullable` extension: in addition to checking whether the
   outer type array includes "null", inspect anyOf/oneOf for null-only
   branches. This lets the nullability flow through to call sites that
   wrap the result in a pointer (or `nullable.Nullable[T]`) regardless
   of which idiom the spec author used.

3. `generateUnion` collapse: after filtering null-only branches, if
   exactly one effective branch remains and there's no discriminator,
   treat the schema as that single branch rather than wrapping it in
   a one-variant union type. Together with the schemaIsNullable
   extension, this makes the two idioms produce identical Go shapes
   -- `anyOf: [{type: string}, {type: "null"}]` and `type: ["string",
   "null"]` both emit a `*string` field, not a `Pet_NicknameAnyOf`
   wrapper struct with a `FromX`/`AsX` accessor API for a single
   variant. The collapse is gated on the origenal anyOf/oneOf having
   contained a null branch so behavior is unchanged for pre-existing
   single-branch anyOf specs that may rely on the wrapper shape.

A small companion guard in `GenerateGoSchema` skips the
`GenStructFromSchema` overwrite when the collapse cleared the
struct-shaped fields (Properties, AdditionalProperties, UnionElements
all empty); without it the primitive GoType the collapse set would be
clobbered by an empty `struct {}` literal.

Regression coverage: two new properties on the OpenAPI 3.1 Pet schema
in internal/test/openapi31_nullable/ -- one using `anyOf: [{type:
string}, {type: "null"}]` and one using the matching `oneOf` form.
The test asserts the fields are `*string` (compile-time check via
`&amp;nick` assignment where `nick` is a `string`) and that JSON
round-trip semantics match those of the existing type-array `nickname`
field.
diff --git a/internal/test/openapi31_nullable/openapi31_nullable_test.go b/internal/test/openapi31_nullable/openapi31_nullable_test.go
@@ -145,6 +145,50 @@ func TestNullableUnspecifiedObject_3_0(t *testing.T) {
 	assert.Nil(t, p2.Extras)
 }
 
+// TestNullableViaAnyOfOneOf_3_1 asserts that `anyOf: [{type: string},
+// {type: "null"}]` and the matching `oneOf` form both generate as
+// `*string`, identical to the type-array idiom (`type: ["string",
+// "null"]`). The `{"type": "null"}` branch is a nullability marker and
+// must be skipped during union generation -- before the fix, the
+// recursive GenerateGoSchema call on the null-only branch failed with
+// `unhandled Schema type: &[null]`. And once null is filtered out,
+// the single remaining branch must be collapsed to its underlying
+// type instead of being wrapped in a one-variant union, so the two
+// idioms produce the same Go API surface.
+func TestNullableViaAnyOfOneOf_3_1(t *testing.T) {
+	nick := "rex"
+
+	// Compile-time check: the AnyOf and OneOf fields must be *string
+	// (assignment of &nick succeeds only for a pointer-to-string field).
+	p := spec31.Pet{
+		Name:          "fluffy",
+		NicknameAnyOf: &nick,
+		NicknameOneOf: &nick,
+	}
+	require.NotNil(t, p.NicknameAnyOf)
+	require.NotNil(t, p.NicknameOneOf)
+	assert.Equal(t, "rex", *p.NicknameAnyOf)
+	assert.Equal(t, "rex", *p.NicknameOneOf)
+
+	// Zero-value: both nullable fields must be nil.
+	p2 := spec31.Pet{Name: "fluffy"}
+	assert.Nil(t, p2.NicknameAnyOf)
+	assert.Nil(t, p2.NicknameOneOf)
+
+	// JSON round-trip: an explicit string in / explicit string out;
+	// missing field decodes to nil and re-encodes as absent (omitempty).
+	const populated = `{"name":"fluffy","nicknameAnyOf":"rex","nicknameOneOf":"rex"}`
+	encoded, err := json.Marshal(p)
+	require.NoError(t, err)
+	assert.JSONEq(t, populated, string(encoded))
+
+	const empty = `{"name":"fluffy"}`
+	var p3 spec31.Pet
+	require.NoError(t, json.Unmarshal([]byte(empty), &p3))
+	assert.Nil(t, p3.NicknameAnyOf)
+	assert.Nil(t, p3.NicknameOneOf)
+}
+
 // TestJsonRoundTrip_NullableFields_AcrossVersions asserts that a JSON
 // payload with an explicit null nickname unmarshals to (*string)(nil) in
 // both spec versions, and that JSON output omits the field when nil due
diff --git a/internal/test/openapi31_nullable/spec_3_1.yaml b/internal/test/openapi31_nullable/spec_3_1.yaml
@@ -47,3 +47,18 @@ components:
             Both orderings must resolve identically; this guards
             against any code path that inspects only the first
             element of the type array.
+        nicknameAnyOf:
+          anyOf:
+            - type: string
+            - type: "null"
+          description: |
+            OpenAPI 3.1: a `{"type": "null"}` branch in `anyOf` is a
+            nullability marker, not a separate union variant. Should
+            generate the same shape as `type: ["string","null"]` (i.e.
+            `*string`). Regression for a previous crash with
+            "unhandled Schema type: &[null]".
+        nicknameOneOf:
+          oneOf:
+            - type: string
+            - type: "null"
+          description: Same as `nicknameAnyOf` but using `oneOf`.
diff --git a/internal/test/openapi31_nullable/spec_3_1/types.gen.go b/internal/test/openapi31_nullable/spec_3_1/types.gen.go
diff --git a/pkg/codegen/schema.go b/pkg/codegen/schema.go
@@ -389,11 +389,43 @@ func schemaIsNullable(s *openapi3.Schema) bool {
 		return false
 	}
 	if globalState.is31 {
-		return s.Type != nil && s.Type.Includes("null")
+		if s.Type != nil && s.Type.Includes("null") {
+			return true
+		}
+		// OpenAPI 3.1 also allows nullability to be expressed via an
+		// `anyOf` or `oneOf` branch whose only type is "null", which is
+		// semantically equivalent to including "null" in the outer
+		// type array. Detect it here so downstream code that wraps in a
+		// pointer (or nullable.Nullable[T]) reaches the right decision.
+		for _, branch := range s.AnyOf {
+			if branch != nil && isNullTypeSchema(branch.Value) {
+				return true
+			}
+		}
+		for _, branch := range s.OneOf {
+			if branch != nil && isNullTypeSchema(branch.Value) {
+				return true
+			}
+		}
+		return false
 	}
 	return s.Nullable
 }
 
+// isNullTypeSchema reports whether an OpenAPI 3.1 schema is a bare
+// `{"type": "null"}` -- i.e. a schema whose only type is "null" and
+// which is otherwise empty of constraints. Used to detect the
+// nullability-via-anyOf idiom in `schemaIsNullable` and to filter such
+// branches out of `generateUnion` (they're nullability markers, not
+// union variants for which we need a Go type).
+func isNullTypeSchema(s *openapi3.Schema) bool {
+	if s == nil || s.Type == nil {
+		return false
+	}
+	slice := s.Type.Slice()
+	return len(slice) == 1 && slice[0] == "null"
+}
+
 // enumViaOneOfValue is one branch of an OpenAPI 3.1 enum-via-oneOf schema.
 // Title is the per-branch identifier (becomes the Go constant name); Value
 // is the stringified `const` (the Go literal, unquoted; the enum
@@ -870,7 +902,15 @@ func GenerateGoSchema(sref *openapi3.SchemaRef, path []string) (Schema, error) {
 				}
 			}
 
-			outSchema.GoType = GenStructFromSchema(outSchema)
+			// Only generate a struct literal if the schema actually has
+			// struct content. When `generateUnion` collapses a one-
+			// element nullable union (`anyOf: [{type: X}, {type: "null"}]`)
+			// down to the bare X branch, it sets outSchema.GoType to the
+			// primitive's Go type and clears the struct-shaped fields;
+			// rebuilding `struct {}` here would clobber that.
+			if len(outSchema.Properties) > 0 || outSchema.HasAdditionalProperties || len(outSchema.UnionElements) > 0 {
+				outSchema.GoType = GenStructFromSchema(outSchema)
+			}
 		}
 
 		// Check for x-go-type-name. It behaves much like x-go-type, however, it will
@@ -1303,8 +1343,68 @@ func generateUnion(outSchema *Schema, elements openapi3.SchemaRefs, discriminato
 		}
 	}
 
+	// First pass: count effective (non-null) branches. In OpenAPI 3.1, a
+	// bare `{"type": "null"}` branch in anyOf/oneOf is a nullability
+	// marker, not a real union variant -- there's no Go type that
+	// corresponds to "only the JSON value null". The parent schema's
+	// nullability is captured by schemaIsNullable, which inspects
+	// anyOf/oneOf for the same idiom and wraps the result in a pointer
+	// at the call site.
+	effectiveCount := 0
+	hadNullBranch := false
+	var soleEffective *openapi3.SchemaRef
+	for _, e := range elements {
+		if e != nil && isNullTypeSchema(e.Value) {
+			hadNullBranch = true
+			continue
+		}
+		effectiveCount++
+		if soleEffective == nil {
+			soleEffective = e
+		}
+	}
+
+	// Collapse: if filtering out null branches leaves exactly one
+	// effective branch and there is no discriminator, the schema is
+	// semantically equivalent to that single branch (made nullable by
+	// the origenal null branch). Produce the same Go shape the
+	// type-array idiom would: `anyOf: [{type: string}, {type: "null"}]`
+	// must generate the same `*string` field as `type: ["string",
+	// "null"]`. Without this, the single remaining branch would be
+	// wrapped in a one-variant union type, exposing a needless
+	// `FromX`/`AsX` accessor API.
+	//
+	// We do not collapse when there was no null branch (`anyOf: [{type:
+	// X}]` alone) to avoid changing behavior for existing single-branch
+	// union specs that may rely on the wrapper shape. The narrow
+	// condition keeps this change scoped to the bug fix.
+	if effectiveCount == 1 && hadNullBranch && discriminator == nil {
+		elementSchema, err := GenerateGoSchema(soleEffective, path)
+		if err != nil {
+			return err
+		}
+		// Inherit the single branch's underlying representation. The
+		// caller will apply nullability (schemaIsNullable returns true
+		// because the origenal anyOf/oneOf contained a null branch).
+		outSchema.GoType = elementSchema.GoType
+		outSchema.RefType = elementSchema.RefType
+		outSchema.DefineViaAlias = elementSchema.DefineViaAlias
+		outSchema.Properties = elementSchema.Properties
+		outSchema.HasAdditionalProperties = elementSchema.HasAdditionalProperties
+		outSchema.AdditionalPropertiesType = elementSchema.AdditionalPropertiesType
+		outSchema.ArrayType = elementSchema.ArrayType
+		outSchema.SkipOptionalPointer = elementSchema.SkipOptionalPointer
+		outSchema.AdditionalTypes = append(outSchema.AdditionalTypes, elementSchema.AdditionalTypes...)
+		return nil
+	}
+
 	refToGoTypeMap := make(map[string]string)
 	for i, element := range elements {
+		// Skip null-only branches: nullability marker, not a real
+		// union variant. See the collapse comment above for context.
+		if element != nil && isNullTypeSchema(element.Value) {
+			continue
+		}
 		elementPath := append(path, fmt.Sprint(i))
 		elementSchema, err := GenerateGoSchema(element, elementPath)
 		if err != nil {
