Add documentation for reducing duplicate field types (#2896)

* Add documentation for reducing duplicate field types with --use-type-alias

* docs: update CLI reference documentation and prompt data

🤖 Generated by GitHub Actions

* Use heading instead of bold for Result section

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: koxudaxi

docs/cli-reference/typing-customization.md

@@ -4198,6 +4198,8 @@ syntax. This feature is experimental.
 
 **Related:** [`--target-python-version`](model-customization.md#target-python-version)
 
+**See also:** [Model Reuse and Deduplication](../model-reuse.md)
+
 !!! tip "Usage"
 
     ```bash

docs/model-reuse.md

@@ -1,4 +1,4 @@
-<!-- related-cli-options: --reuse-model, --reuse-scope, --shared-module-name, --collapse-root-models, --disable-warnings -->
+<!-- related-cli-options: --reuse-model, --reuse-scope, --shared-module-name, --collapse-root-models, --disable-warnings, --use-type-alias -->
 
 # Model Reuse and Deduplication
 
@@ -12,6 +12,7 @@ When generating models from schemas, you may encounter duplicate model definitio
 | `--reuse-scope` | Control scope of deduplication (`root` or `tree`) |
 | `--shared-module-name` | Name for shared module in multi-file output |
 | `--collapse-root-models` | Inline root models instead of creating wrappers |
+| `--use-type-alias` | Create TypeAlias for reusable field types (see [Reducing Duplicate Field Types](#reducing-duplicate-field-types)) |
 
 ---
 
@@ -243,10 +244,98 @@ models/
 
 ---
 
+## Reducing Duplicate Field Types
+
+When multiple classes share the same field type with identical constraints or metadata, you can reduce duplication by defining the type once in `$defs` and referencing it with `$ref`. Combined with `--use-type-alias`, this creates a single TypeAlias that's reused across all classes.
+
+### Problem: Duplicate Annotated Fields
+
+Without using `$ref`, each class gets its own inline field definition:
+
+```python
+class ClassA(BaseModel):
+    place_name: Annotated[str, Field(alias='placeName')]  # Duplicate!
+
+class ClassB(BaseModel):
+    place_name: Annotated[str, Field(alias='placeName')]  # Duplicate!
+```
+
+### Solution: Use `$defs` with `--use-type-alias`
+
+**Step 1: Define the shared type in `$defs`**
+
+```json
+{
+  "$defs": {
+    "PlaceName": {
+      "type": "string",
+      "title": "PlaceName",
+      "description": "A place name"
+    },
+    "ClassA": {
+      "type": "object",
+      "properties": {
+        "place_name": { "$ref": "#/$defs/PlaceName" }
+      }
+    },
+    "ClassB": {
+      "type": "object",
+      "properties": {
+        "place_name": { "$ref": "#/$defs/PlaceName" }
+      }
+    }
+  }
+}
+```
+
+**Step 2: Generate with `--use-type-alias`**
+
+```bash
+datamodel-codegen \
+  --input schema.json \
+  --output model.py \
+  --use-type-alias
+```
+
+### Result: Single TypeAlias reused across classes
+
+```python
+PlaceName = TypeAliasType(
+    "PlaceName",
+    Annotated[str, Field(..., description='A place name', title='PlaceName')],
+)
+
+
+class ClassA(BaseModel):
+    place_name: PlaceName  # Reuses the TypeAlias
+
+
+class ClassB(BaseModel):
+    place_name: PlaceName  # Reuses the TypeAlias
+```
+
+### Benefits
+
+- **Single source of truth** - Field type is defined once
+- **Easier maintenance** - Change the type in one place
+- **Cleaner generated code** - No redundant annotations
+- **Type safety** - All fields share the exact same type
+
+### When to Use This Pattern
+
+This pattern is ideal when:
+
+- Multiple classes share fields with the same constraints (e.g., `minLength`, `pattern`)
+- Fields have identical metadata (e.g., `description`, `examples`)
+- You want to ensure type consistency across your schema
+
+---
+
 ## See Also
 
 - [CLI Reference: `--reuse-model`](cli-reference/model-customization.md#reuse-model)
 - [CLI Reference: `--reuse-scope`](cli-reference/model-customization.md#reuse-scope)
 - [CLI Reference: `--collapse-root-models`](cli-reference/model-customization.md#collapse-root-models)
+- [CLI Reference: `--use-type-alias`](cli-reference/typing-customization.md#use-type-alias)
 - [Root Models and Type Aliases](root-model-and-type-alias.md)
 - [FAQ: Performance](faq.md#-performance)

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

@@ -0,0 +1,36 @@
+# generated by datamodel-codegen:
+#   filename:  reduce_duplicate_field_types.json
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+from typing_extensions import TypeAliasType
+
+PlaceName = TypeAliasType(
+    "PlaceName",
+    Annotated[
+        str,
+        Field(
+            ...,
+            description='A place name with alias',
+            examples=['Tokyo', 'New York'],
+            title='PlaceName',
+        ),
+    ],
+)
+
+
+class ClassA(BaseModel):
+    place_name: PlaceName
+    other_field: int | None = None
+
+
+class ClassB(BaseModel):
+    place_name: PlaceName
+    description: str | None = None
+
+
+Model = TypeAliasType("Model", Annotated[ClassA | ClassB, Field(..., title='Model')])

tests/data/jsonschema/reduce_duplicate_field_types.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Model",
+  "$defs": {
+    "PlaceName": {
+      "type": "string",
+      "title": "PlaceName",
+      "description": "A place name with alias",
+      "examples": ["Tokyo", "New York"]
+    },
+    "ClassA": {
+      "type": "object",
+      "title": "ClassA",
+      "properties": {
+        "place_name": {
+          "$ref": "#/$defs/PlaceName"
+        },
+        "other_field": {
+          "type": "integer"
+        }
+      },
+      "required": ["place_name"]
+    },
+    "ClassB": {
+      "type": "object",
+      "title": "ClassB",
+      "properties": {
+        "place_name": {
+          "$ref": "#/$defs/PlaceName"
+        },
+        "description": {
+          "type": "string"
+        }
+      },
+      "required": ["place_name"]
+    }
+  },
+  "anyOf": [
+    {"$ref": "#/$defs/ClassA"},
+    {"$ref": "#/$defs/ClassB"}
+  ]
+}

tests/main/jsonschema/test_main_jsonschema.py

@@ -7540,3 +7540,20 @@ def test_ref_nullable_with_extra_creates_model(output_file: Path) -> None:
         expected_file="ref_nullable_with_extra.py",
         extra_args=["--output-model-type", "pydantic_v2.BaseModel", "--strict-nullable"],
     )
+
+
+def test_reduce_duplicate_field_types(output_file: Path) -> None:
+    """Test reducing duplicate field types using $ref and --use-type-alias.
+
+    When multiple classes share the same field type defined in $defs,
+    using --use-type-alias creates a single TypeAlias that's reused across classes.
+    This is the recommended pattern to avoid duplicate Annotated field definitions.
+    """
+    run_main_and_assert(
+        input_path=JSON_SCHEMA_DATA_PATH / "reduce_duplicate_field_types.json",
+        output_path=output_file,
+        input_file_type="jsonschema",
+        assert_func=assert_file_content,
+        expected_file="reduce_duplicate_field_types.py",
+        extra_args=["--output-model-type", "pydantic_v2.BaseModel", "--use-type-alias"],
+    )