Fix duplicate model generation for $ref with nullable

Author: koxudaxi

src/datamodel_code_generator/parser/jsonschema.py

@@ -477,6 +477,27 @@ def has_ref_with_schema_keywords(self) -> bool:
                 schema_affecting_fields |= {"extras"}
         return bool(schema_affecting_fields)
 
+    @cached_property
+    def is_ref_with_nullable_only(self) -> bool:
+        """Check if schema has $ref with only nullable: true (no other schema-affecting keywords).
+
+        This is used to avoid creating duplicate models when a $ref is combined
+        with nullable: true. In such cases, the reference should be used directly
+        with Optional type annotation instead of merging schemas.
+        """
+        if not self.ref or self.nullable is not True:
+            return False
+        other_fields = get_fields_set(self) - {"ref", "nullable"} - self.__metadata_only_fields__ - {"extras"}
+        if other_fields:
+            return False
+        if self.extras:
+            schema_affecting_extras = {
+                k for k in self.extras if k not in self.__metadata_only_fields__ and not k.startswith("x-")
+            }
+            if schema_affecting_extras:
+                return False
+        return True
+
 
 @lru_cache
 def get_ref_type(ref: str) -> JSONReference:
@@ -2700,6 +2721,12 @@ def parse_item(  # noqa: PLR0911, PLR0912, PLR0914
                 item,
                 root_type_path,
             )
+        # Handle $ref + nullable-only case without merging to avoid duplicate models
+        if item.is_ref_with_nullable_only and item.ref:
+            ref_data_type = self.get_ref_data_type(item.ref)
+            if self.strict_nullable:
+                return self.data_type(data_types=[ref_data_type], is_optional=True)
+            return ref_data_type
         if item.has_ref_with_schema_keywords:
             item = self._merge_ref_with_schema(item)
         if item.ref:
@@ -3523,7 +3550,8 @@ def parse_obj(  # noqa: PLR0912
         path: list[str],
     ) -> None:
         """Parse a JsonSchemaObject by dispatching to appropriate parse methods."""
-        if obj.has_ref_with_schema_keywords:
+        # Skip merge for $ref + nullable-only (handled by ref resolution in parse_item)
+        if obj.has_ref_with_schema_keywords and not obj.is_ref_with_nullable_only:
             obj = self._merge_ref_with_schema(obj)
 
         if obj.is_array:

tests/data/expected/main/jsonschema/ref_nullable_only.py

@@ -0,0 +1,17 @@
+# generated by datamodel-codegen:
+#   filename:  ref_nullable_only.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    name: str
+
+
+class Model(BaseModel):
+    user_a: User | None = None
+    user_b: User | None = None
+    user_c: User | None = None

tests/data/expected/main/jsonschema/ref_nullable_only_strict.py

@@ -0,0 +1,17 @@
+# generated by datamodel-codegen:
+#   filename:  ref_nullable_only.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class User(BaseModel):
+    name: str
+
+
+class Model(BaseModel):
+    user_a: User | None = None
+    user_b: User | None = None
+    user_c: User | None = None

tests/data/expected/main/jsonschema/ref_nullable_with_constraint.py

@@ -0,0 +1,15 @@
+# generated by datamodel-codegen:
+#   filename:  ref_nullable_with_constraint.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from pydantic import BaseModel, RootModel, constr
+
+
+class Model(BaseModel):
+    constrained_string: constr(min_length=5) | None = None
+
+
+class StringType(RootModel[str]):
+    root: str

tests/data/expected/main/jsonschema/ref_nullable_with_extra.py

@@ -0,0 +1,19 @@
+# generated by datamodel-codegen:
+#   filename:  ref_nullable_with_extra.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class UserWithExtra(BaseModel):
+    name: str | None = None
+
+
+class Model(BaseModel):
+    user_with_extra: UserWithExtra | None = None
+
+
+class User(BaseModel):
+    name: str | None = None

tests/data/expected/main/jsonschema/ref_nullable_with_metadata.py

@@ -0,0 +1,19 @@
+# generated by datamodel-codegen:
+#   filename:  ref_nullable_with_metadata.yaml
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class User(BaseModel):
+    name: str
+
+
+class Model(BaseModel):
+    user_with_title: User | None = Field(
+        None,
+        description='A user reference with additional metadata',
+        title='User with Title',
+    )

tests/data/jsonschema/ref_nullable_only.yaml

@@ -0,0 +1,19 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+definitions:
+  User:
+    type: object
+    properties:
+      name:
+        type: string
+    required:
+      - name
+type: object
+properties:
+  user_a:
+    $ref: "#/definitions/User"
+    nullable: true
+  user_b:
+    $ref: "#/definitions/User"
+    nullable: true
+  user_c:
+    $ref: "#/definitions/User"

tests/data/jsonschema/ref_nullable_with_constraint.yaml

@@ -0,0 +1,10 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+definitions:
+  StringType:
+    type: string
+type: object
+properties:
+  constrained_string:
+    $ref: "#/definitions/StringType"
+    nullable: true
+    minLength: 5

tests/data/jsonschema/ref_nullable_with_extra.yaml

@@ -0,0 +1,16 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+definitions:
+  User:
+    type: object
+    properties:
+      name:
+        type: string
+type: object
+properties:
+  user_with_extra:
+    $ref: "#/definitions/User"
+    nullable: true
+    if:
+      properties:
+        name:
+          const: admin

tests/data/jsonschema/ref_nullable_with_metadata.yaml

@@ -0,0 +1,16 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+definitions:
+  User:
+    type: object
+    properties:
+      name:
+        type: string
+    required:
+      - name
+type: object
+properties:
+  user_with_title:
+    $ref: "#/definitions/User"
+    nullable: true
+    title: User with Title
+    description: A user reference with additional metadata