Normalizer: new rule LOOSE_NULL_DEFINITIONS to allow more null definitions in 3.0 spec. (#23932)

* 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>

* address PR feedback

* add LOOSE_NULL_DEFINITIONS to normalizer rule

* update doc, tests

* fix tests

* update

* update doc

---------

Co-authored-by: eric-r-driggs <eric.driggs@disney.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Eric Driggs <ericdriggs@users.noreply.github.com>

Author: 4 people

docs/customization.md

@@ -644,6 +644,13 @@ Example:
 java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -g java -i modules/openapi-generator/src/test/resources/3_0/required-properties.yaml -o /tmp/java-okhttp/ --openapi-normalizer NORMALIZER_CLASS=org.openapitools.codegen.OpenAPINormalizerTest$RemoveRequiredNormalizer
 ```
 
+- `LOOSE_NULL_DEFINITIONS`: When set to true, allow more schema definitions in OpenAPI 3.0 spec to be the same as `null` in OpenAPI 3.1 spec by setting ModelUtils.looseNullDefinitions to true.
+
+Example:
+```
+java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -g java -i modules/openapi-generator/src/test/resources/bugs/issue_anyof_bare_nullable_object.yaml -o /tmp/java-okhttp/ --openapi-normalizer LOOSE_NULL_DEFINITIONS=true
+```
+
 - `REMOVE_PROPERTIES_FROM_TYPE_OTHER_THAN_OBJECT`: When set to true, remove the "properties" of a schema with type other than "object".
 
 Example:

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

@@ -165,6 +165,9 @@ public class OpenAPINormalizer {
     // when set to true, sort model properties by name to ensure deterministic output
     final String SORT_MODEL_PROPERTIES = "SORT_MODEL_PROPERTIES";
 
+    // when set to true, some more schema definitions are considered as `null` in 3.1 spec
+    final String LOOSE_NULL_DEFINITIONS = "LOOSE_NULL_DEFINITIONS";
+
     // ============= end of rules =============
 
     /**
@@ -225,6 +228,7 @@ public OpenAPINormalizer(OpenAPI openAPI, Map<String, String> inputRules) {
         ruleNames.add(SIMPLIFY_ONEOF_ANYOF_ENUM);
         ruleNames.add(REMOVE_PROPERTIES_FROM_TYPE_OTHER_THAN_OBJECT);
         ruleNames.add(SORT_MODEL_PROPERTIES);
+        ruleNames.add(LOOSE_NULL_DEFINITIONS);
         ruleNames.add(REPLACE_ONE_OF_BY_DISCRIMINATOR_MAPPING);
 
         // rules that are default to true
@@ -341,6 +345,11 @@ public void processRules(Map<String, String> inputRules) {
         if (bearerAuthSecuritySchemeName != null) {
             rules.put(SET_BEARER_AUTH_FOR_NAME, true);
         }
+
+        // update ModelUtils to allow loose null definitions if the normalizer rule LOOSE_NULL_DEFINITIONS is set
+        if (Boolean.TRUE.equals(rules.get(LOOSE_NULL_DEFINITIONS))) {
+            ModelUtils.looseNullDefinitions = true;
+        }
     }
 
     /**

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

@@ -81,6 +81,10 @@ public class ModelUtils {
     private static final ObjectMapper JSON_MAPPER;
     private static final ObjectMapper YAML_MAPPER;
 
+    // allow more schema definitions to be the `null` type in 3.1 spec
+    // e.g. {type: object, nullable: true} which is any type that's nullable
+    public static boolean looseNullDefinitions = false;
+
     static {
         JSON_MAPPER = ObjectMapperFactory.createJson();
         YAML_MAPPER = ObjectMapperFactory.createYaml();
@@ -2394,6 +2398,18 @@ public static boolean isNullTypeSchema(OpenAPI openAPI, Schema schema) {
             return false;
         }
 
+        // OpenAPI 3.0.x: nullable object with no properties or constraints expresses nullability, which
+        // is any type that's nullable, i.e. {type: object, nullable: true}
+        // given that the normalizer rule `LOOSE_NULL_DEFINITIONS` is enabled
+        if (looseNullDefinitions &&
+                !(schema instanceof JsonSchema) // 3.0.x only
+                && "object".equals(schema.getType())
+                && Boolean.TRUE.equals(schema.getNullable())
+                && schema.get$ref() == null
+                && schema.getAdditionalProperties() == 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/OpenAPINormalizerTest.java

@@ -1834,7 +1834,7 @@ public Schema normalizeSchema(Schema schema, Set<Schema> visitedSchemas) {
     }
 
     @Test
-    public void testREPLACE_ONE_OF_BY_DISCRIMINATOR_MAPPING() {
+    public void testReplaceOneOfByDiscriminatorMapping() {
         OpenAPI openAPI = TestUtils.parseSpec("src/test/resources/3_0/oneOf_issue_23527.yaml");
 
         Map<String, String> inputRules = Map.of("REPLACE_ONE_OF_BY_DISCRIMINATOR_MAPPING", "true");
@@ -1847,12 +1847,11 @@ public void testREPLACE_ONE_OF_BY_DISCRIMINATOR_MAPPING() {
     }
 
     @Test
-    public void issue_14769() {
+    public void testIssue14769() {
         OpenAPI openAPI = TestUtils.parseSpec("src/test/resources/3_0/oneOf_issue_14769.yaml");
         Map<String, String> inputRules = Map.of("REPLACE_ONE_OF_BY_DISCRIMINATOR_MAPPING", "true");
         OpenAPINormalizer openAPINormalizer = new OpenAPINormalizer(openAPI, inputRules);
         openAPINormalizer.normalize();
-//        ModelUtils.dumpAsYaml(openAPI);
         Schema vehicle = openAPI.getComponents().getSchemas().get("Vehicle");
         Map<String, String> mapping = vehicle.getDiscriminator().getMapping();
         assertEquals(mapping, Map.of("car", "#/components/schemas/Car", "plane", "#/components/schemas/Plane" ));
@@ -1865,15 +1864,36 @@ public void issue_14769() {
     }
 
     @Test
-    public void oneOf_issue_23276() {
+    public void oneOfIssue23276() {
         OpenAPI openAPI = TestUtils.parseSpec("src/test/resources/3_0/oneOf_issue_23276.yaml");
         Map<String, String> inputRules = Map.of("REPLACE_ONE_OF_BY_DISCRIMINATOR_MAPPING", "true");
         OpenAPINormalizer openAPINormalizer = new OpenAPINormalizer(openAPI, inputRules);
         openAPINormalizer.normalize();
-//         ModelUtils.dumpAsYaml(openAPI);
         Schema payload = (Schema)openAPI.getComponents().getSchemas().get("DeviceLifecycleEvent").getProperties().get("payload");
         // inline oneOf are not converted
         assertNotNull(payload.getOneOf());
     }
 
+    @Test
+    public void testLooseNullDefinitions() {
+        OpenAPI openAPI = TestUtils.parseSpec("src/test/resources/bugs/issue_anyof_bare_nullable_object.yaml");
+
+        Schema<?> order = openAPI.getComponents().getSchemas().get("Order");
+        assertEquals(((Schema) order.getProperties().get("shippingAddress").getAnyOf().get(0)).get$ref(),  "#/components/schemas/Address");
+        assertEquals(((Schema) order.getProperties().get("shippingAddress").getAnyOf().get(1)).getNullable(), true);
+        assertEquals(((Schema) order.getProperties().get("shippingAddress").getAnyOf().get(1)).getType(), "object");
+
+        Map<String, String> options = Map.of("LOOSE_NULL_DEFINITIONS", "true");
+        OpenAPINormalizer openAPINormalizer = new OpenAPINormalizer(openAPI, options);
+        openAPINormalizer.normalize();
+
+        Schema<?> order2 = openAPI.getComponents().getSchemas().get("Order");
+        assertEquals(order2.getProperties().get("shippingAddress").get$ref(),  null);
+        assertEquals(order2.getProperties().get("shippingAddress").getNullable(), true);
+        assertEquals( ((Schema) order2.getProperties().get("shippingAddress").getAllOf().get(0)).get$ref(), "#/components/schemas/Address");
+
+        // reset to false after tests
+        ModelUtils.looseNullDefinitions = false;
+    }
+
 }

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

@@ -654,6 +654,43 @@ public void isNullTypeSchemaTest() {
 
         schema = openAPI.getComponents().getSchemas().get("JustDescription");
         assertFalse(ModelUtils.isNullTypeSchema(openAPI, schema));
+
+        // {type: "object", nullable: true} with no properties/constraints expresses nullability (OAS 3.0.3)
+        // but only if the normalizer rule `LOOSE_NULL_DEFINITIONS` is enabled
+        schema = openAPI.getComponents().getSchemas().get("BareNullableObject");
+        assertFalse(ModelUtils.isNullTypeSchema(openAPI, schema));
+
+        // {type: "object", nullable: true} WITH properties is a real object, not expressing nullability
+        // whether normalizer rule `LOOSE_NULL_DEFINITIONS` is enabled or not
+        schema = openAPI.getComponents().getSchemas().get("NullableObjectWithProperties");
+        assertFalse(ModelUtils.isNullTypeSchema(openAPI, schema));
+
+        // {type: "object", nullable: true, additionalProperties: ...} is a nullable map, not expressing nullability
+        // whether normalizer rule `LOOSE_NULL_DEFINITIONS` is enabled or not
+        schema = openAPI.getComponents().getSchemas().get("NullableObjectMap");
+        assertFalse(ModelUtils.isNullTypeSchema(openAPI, schema));
+    }
+
+    @Test
+    public void isNullTypeSchemaTestBareNullableObject() {
+        OpenAPI openAPI = TestUtils.parseSpec(
+                "src/test/resources/bugs/issue_anyof_bare_nullable_object.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} which is just any type that's also nullable
+        // when normalizer rule `LOOSE_NULL_DEFINITIONS` is NOT enabled
+        Schema bareNullableObject = anyOf.get(1);
+        assertFalse(ModelUtils.isNullTypeSchema(openAPI, bareNullableObject),
+                "not `null` (3.1 spec) as normalizer rule `LOOSE_NULL_DEFINITIONS` is NOT enabled");
     }
 
     @Test
@@ -695,6 +732,12 @@ 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 type — it's a real
+        // nullable object. Nullability in 3.1 is expressed via type: ["object", "null"].
+        // whether normalizer rule `LOOSE_NULL_DEFINITIONS` is enabled or not
+        schema = openAPI.getComponents().getSchemas().get("BareNullableObject");
+        assertFalse(ModelUtils.isNullTypeSchema(openAPI, schema));
     }
 
     @Test

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

@@ -104,4 +104,18 @@ components:
         - $ref: '#/components/schemas/IntegerRef'
         - $ref: '#/components/schemas/StringRef'
     JustDescription:
-      description: A schema with just description
+      description: A schema with just description
+    BareNullableObject:
+      type: object
+      nullable: true
+    NullableObjectWithProperties:
+      type: object
+      nullable: true
+      properties:
+        name:
+          type: string
+    NullableObjectMap:
+      type: object
+      nullable: true
+      additionalProperties:
+        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
+    BareNullableObject:
+      type: object
+      nullable: true

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

@@ -0,0 +1,44 @@
+openapi: 3.0.3
+info:
+  title: anyOf bare nullable object 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