fix: recognize {type: object, nullable: true} as null-type schema in OpenAPI 3.0.x

The SIMPLIFY_ONEOF_ANYOF normalizer failed to simplify anyOf schemas
where the nullable branch uses {type: "object", nullable: true} instead
of an untyped schema or {type: "null"}. This caused Java (and likely
other) code generators to produce Object or synthetic wrapper classes
instead of the intended typed nullable field.

This pattern is a valid OpenAPI 3.0.x idiom for expressing nullability
alongside a $ref in anyOf/oneOf. It is produced by apispec >= 6.7.1
(the most widely used OpenAPI spec generator for Python/Flask/Marshmallow)
and potentially other spec generators.

Root cause: isNullTypeSchema() did not recognize an empty nullable object
({type: "object", nullable: true} with no properties and no $ref) as a
null-type schema. The fix adds a check for this pattern, scoped to 3.0.x
only via !(schema instanceof JsonSchema), since OpenAPI 3.1 expresses
nullability differently via type arrays.

Test coverage:
- isNullTypeSchemaTest: 3.0 sentinel (true), sentinel with properties (false)
- isNullTypeSchemaTestWith31Spec: 3.1 sentinel correctly returns false
- isNullTypeSchemaInlineAnyOfSentinelTest: inline anyOf sub-schema recognized
- testAnyOfNullableObjectSentinelResolvesToTypedField: end-to-end Java
  codegen produces Address field, no synthetic OrderShippingAddress wrapper

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

Author: eric-driggs

modules/openapi-generator/src/main/java/org/openapitools/codegen/utils/ModelUtils.java

@@ -2363,6 +2363,14 @@ public static boolean isNullTypeSchema(OpenAPI openAPI, Schema schema) {
             return false;
         }
 
+        // OpenAPI 3.0.x: empty nullable object is a null-type schema
+        if (!(schema instanceof JsonSchema) // 3.0.x only
+                && "object".equals(schema.getType())
+                && Boolean.TRUE.equals(schema.getNullable())
+                && schema.get$ref() == null) {
+            return true;
+        }
+
         // convert referenced enum of null only to `nullable:true`
         if (schema.getEnum() != null && schema.getEnum().size() == 1) {
             if ("null".equals(String.valueOf(schema.getEnum().get(0)))) {

modules/openapi-generator/src/test/java/org/openapitools/codegen/java/JavaClientCodegenTest.java

@@ -4325,4 +4325,18 @@ public void testJspecify(String library, boolean useSpringBoot4, boolean hasJspe
                 .fileContains("@org.jspecify.annotations.NullMarked");
 
     }
+
+    @Test(description = "anyOf with $ref and {type: object, nullable: true} should resolve to typed nullable field, not Object")
+    public void testAnyOfNullableObjectSentinelResolvesToTypedField() {
+        Map<String, File> files = generateFromContract(
+                "src/test/resources/bugs/issue_anyof_nullable_object_sentinel.yaml",
+                JavaClientCodegen.JERSEY3);
+
+        JavaFileAssert.assertThat(files.get("Order.java"))
+                .fileContains("Address")
+                .fileDoesNotContain("OrderShippingAddress", "Object getShippingAddress");
+
+        Assert.assertNull(files.get("OrderShippingAddress.java"),
+                "Should not generate synthetic anyOf wrapper; the anyOf should simplify to Address");
+    }
 }

modules/openapi-generator/src/test/java/org/openapitools/codegen/utils/ModelUtilsTest.java

@@ -654,6 +654,35 @@ public void isNullTypeSchemaTest() {
 
         schema = openAPI.getComponents().getSchemas().get("JustDescription");
         assertFalse(ModelUtils.isNullTypeSchema(openAPI, schema));
+
+        // {type: "object", nullable: true} with no properties is a null sentinel (apispec 6.7.1+)
+        schema = openAPI.getComponents().getSchemas().get("NullableObjectSentinel");
+        assertTrue(ModelUtils.isNullTypeSchema(openAPI, schema));
+
+        // {type: "object", nullable: true} WITH properties is a real object, not a null sentinel
+        schema = openAPI.getComponents().getSchemas().get("NullableObjectWithProperties");
+        assertFalse(ModelUtils.isNullTypeSchema(openAPI, schema));
+    }
+
+    @Test
+    public void isNullTypeSchemaInlineAnyOfSentinelTest() {
+        OpenAPI openAPI = TestUtils.parseSpec(
+                "src/test/resources/bugs/issue_anyof_nullable_object_sentinel.yaml");
+        Schema order = (Schema) openAPI.getComponents().getSchemas().get("Order");
+        Schema shippingProp = (Schema) order.getProperties().get("shippingAddress");
+        assertNotNull(shippingProp.getAnyOf(), "shippingAddress should have anyOf");
+
+        List<Schema> anyOf = shippingProp.getAnyOf();
+        assertEquals(anyOf.size(), 2);
+
+        // first sub-schema is the $ref to Address
+        Schema refSchema = anyOf.get(0);
+        assertFalse(ModelUtils.isNullTypeSchema(openAPI, refSchema));
+
+        // second sub-schema is {type: object, nullable: true} — the sentinel
+        Schema sentinel = anyOf.get(1);
+        assertTrue(ModelUtils.isNullTypeSchema(openAPI, sentinel),
+                "Should recognize {type: object, nullable: true} as null sentinel");
     }
 
     @Test
@@ -695,6 +724,11 @@ public void isNullTypeSchemaTestWith31Spec() {
 
         schema = openAPI.getComponents().getSchemas().get("JustDescription");
         assertFalse(ModelUtils.isNullTypeSchema(openAPI, schema));
+
+        // In 3.1, {type: object, nullable: true} is NOT a null sentinel — it's a real
+        // nullable object. Nullability in 3.1 is expressed via type: ["object", "null"].
+        schema = openAPI.getComponents().getSchemas().get("NullableObjectSentinel");
+        assertFalse(ModelUtils.isNullTypeSchema(openAPI, schema));
     }
 
     @Test

modules/openapi-generator/src/test/resources/3_0/null_schema_test.yaml

@@ -104,4 +104,13 @@ components:
         - $ref: '#/components/schemas/IntegerRef'
         - $ref: '#/components/schemas/StringRef'
     JustDescription:
-      description: A schema with just description
+      description: A schema with just description
+    NullableObjectSentinel:
+      type: object
+      nullable: true
+    NullableObjectWithProperties:
+      type: object
+      nullable: true
+      properties:
+        name:
+          type: string

modules/openapi-generator/src/test/resources/3_1/null_schema_test.yaml

@@ -105,3 +105,6 @@ components:
         - $ref: '#/components/schemas/StringRef'
     JustDescription:
       description: A schema with just description
+    NullableObjectSentinel:
+      type: object
+      nullable: true

modules/openapi-generator/src/test/resources/bugs/issue_anyof_nullable_object_sentinel.yaml

@@ -0,0 +1,44 @@
+openapi: 3.0.3
+info:
+  title: anyOf nullable object sentinel test
+  description: >
+    Tests that anyOf with a $ref and {type: object, nullable: true} (no properties)
+    is simplified to a typed nullable field, not Object.
+    This pattern is produced by apispec 6.7.1+ for OpenAPI 3.0.x specs.
+  version: 1.0.0
+paths:
+  /orders/{orderId}:
+    get:
+      operationId: getOrder
+      parameters:
+        - name: orderId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Order'
+components:
+  schemas:
+    Order:
+      type: object
+      properties:
+        id:
+          type: string
+        shippingAddress:
+          anyOf:
+            - $ref: '#/components/schemas/Address'
+            - type: object
+              nullable: true
+    Address:
+      type: object
+      properties:
+        street:
+          type: string
+        city:
+          type: string