Add scoped alias support for class-specific field renaming (#2599)

* Add support for field aliases with scoped and flat formats in model generation

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Add aliases data path and update test to use it for hierarchical aliases

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: koxudaxi

README.md

@@ -507,7 +507,11 @@ Model customization:
   --use-title-as-name   use titles as class names of models
 
 Template customization:
-  --aliases ALIASES     Alias mapping file
+  --aliases ALIASES     Alias mapping file (JSON) for renaming fields. Supports hierarchical
+                        formats: Flat: {''field'': ''alias''} applies to all occurrences.
+                        Scoped: {''ClassName.field'': ''alias''} applies to specific class.
+                        Priority: scoped > flat. Example: {''User.name'': ''user_name'',
+                        ''Address.name'': ''addr_name'', ''id'': ''id_''}
   --custom-file-header CUSTOM_FILE_HEADER
                         Custom file header
   --custom-file-header-path CUSTOM_FILE_HEADER_PATH

docs/aliases.md

@@ -0,0 +1,109 @@
+# Field Aliases
+
+The `--aliases` option allows you to rename fields in the generated models. This is useful when you want to use different Python field names than those defined in the schema while preserving the original names as serialization aliases.
+
+## Basic Usage
+
+```bash
+datamodel-codegen --input schema.json --output model.py --aliases aliases.json
+```
+
+## Alias File Format
+
+The alias file is a JSON file that maps original field names to their Python aliases.
+
+### Flat Format (Traditional)
+
+The simplest format applies aliases to all fields with the matching name, regardless of which class they belong to:
+
+```json
+{
+  "id": "id_",
+  "type": "type_",
+  "class": "class_"
+}
+```
+
+This will rename all fields named `id` to `id_`, all fields named `type` to `type_`, etc.
+
+### Scoped Format (Class-Specific)
+
+When you have the same field name in multiple classes but want different aliases for each, use the scoped format with `ClassName.field`:
+
+```json
+{
+  "User.name": "user_name",
+  "Address.name": "address_name",
+  "name": "default_name"
+}
+```
+
+**Priority**: Scoped aliases take priority over flat aliases. In the example above:
+- `User.name` will be renamed to `user_name`
+- `Address.name` will be renamed to `address_name`
+- Any other class with a `name` field will use `default_name`
+
+## Example
+
+### Input Schema
+
+```json
+{
+  "type": "object",
+  "title": "Root",
+  "properties": {
+    "name": {"type": "string"},
+    "user": {
+      "type": "object",
+      "title": "User",
+      "properties": {
+        "name": {"type": "string"},
+        "id": {"type": "integer"}
+      }
+    },
+    "address": {
+      "type": "object",
+      "title": "Address",
+      "properties": {
+        "name": {"type": "string"},
+        "city": {"type": "string"}
+      }
+    }
+  }
+}
+```
+
+### Alias File
+
+```json
+{
+  "Root.name": "root_name",
+  "User.name": "user_name",
+  "Address.name": "address_name"
+}
+```
+
+### Generated Output
+
+```python
+from pydantic import BaseModel, Field
+
+class User(BaseModel):
+    user_name: str | None = Field(None, alias='name')
+    id: int | None = None
+
+class Address(BaseModel):
+    address_name: str | None = Field(None, alias='name')
+    city: str | None = None
+
+class Root(BaseModel):
+    root_name: str | None = Field(None, alias='name')
+    user: User | None = None
+    address: Address | None = None
+```
+
+## Notes
+
+- The `ClassName` in scoped format must match the generated Python class name (after title conversion)
+- When using `--use-title-as-name`, the class name is derived from the `title` property in the schema
+- Aliases are applied during code generation, so the original field names are preserved as Pydantic `alias` values for proper serialization/deserialization

docs/index.md

@@ -499,7 +499,11 @@ Model customization:
   --use-title-as-name   use titles as class names of models
 
 Template customization:
-  --aliases ALIASES     Alias mapping file
+  --aliases ALIASES     Alias mapping file (JSON) for renaming fields. Supports hierarchical
+                        formats: Flat: {''field'': ''alias''} applies to all occurrences.
+                        Scoped: {''ClassName.field'': ''alias''} applies to specific class.
+                        Priority: scoped > flat. Example: {''User.name'': ''user_name'',
+                        ''Address.name'': ''addr_name'', ''id'': ''id_''}
   --custom-file-header CUSTOM_FILE_HEADER
                         Custom file header
   --custom-file-header-path CUSTOM_FILE_HEADER_PATH

src/datamodel_code_generator/arguments.py

@@ -541,7 +541,12 @@ def start_section(self, heading: str | None) -> None:
 # ======================================================================================
 template_options.add_argument(
     "--aliases",
-    help="Alias mapping file",
+    help="Alias mapping file (JSON) for renaming fields. "
+    "Supports hierarchical formats: "
+    "Flat: {'field': 'alias'} applies to all occurrences. "
+    "Scoped: {'ClassName.field': 'alias'} applies to specific class. "
+    "Priority: scoped > flat. "
+    "Example: {'User.name': 'user_name', 'Address.name': 'addr_name', 'id': 'id_'}",
     type=Path,
 )
 template_options.add_argument(

src/datamodel_code_generator/parser/graphql.py

@@ -510,7 +510,9 @@ def parse_object_like(
 
         for field_name, field in obj.fields.items():
             field_name_, alias = self.model_resolver.get_valid_field_name_and_alias(
-                field_name, excludes=exclude_field_names
+                field_name,
+                excludes=exclude_field_names,
+                class_name=obj.name,
             )
             exclude_field_names.add(field_name_)
 

src/datamodel_code_generator/parser/jsonschema.py

@@ -933,7 +933,10 @@ def _parse_object_common_part(  # noqa: PLR0913, PLR0917
         if obj.properties:
             fields.extend(
                 self.parse_object_fields(
-                    obj, path, get_module_name(name, None, treat_dot_as_module=self.treat_dot_as_module)
+                    obj,
+                    path,
+                    get_module_name(name, None, treat_dot_as_module=self.treat_dot_as_module),
+                    class_name=name,
                 )
             )
         # ignore an undetected object
@@ -1004,6 +1007,7 @@ def _parse_all_of_item(  # noqa: PLR0913, PLR0917
                     all_of_item,
                     path,
                     module_name,
+                    class_name=name,
                 )
 
                 if object_fields:
@@ -1107,6 +1111,7 @@ def parse_object_fields(
         obj: JsonSchemaObject,
         path: list[str],
         module_name: Optional[str] = None,  # noqa: UP045
+        class_name: Optional[str] = None,  # noqa: UP045
     ) -> list[DataModelFieldBase]:
         """Parse object properties into a list of data model fields."""
         properties: dict[str, JsonSchemaObject | bool] = {} if obj.properties is None else obj.properties
@@ -1116,7 +1121,9 @@ def parse_object_fields(
         exclude_field_names: set[str] = set()
         for original_field_name, field in properties.items():
             field_name, alias = self.model_resolver.get_valid_field_name_and_alias(
-                original_field_name, excludes=exclude_field_names
+                original_field_name,
+                excludes=exclude_field_names,
+                class_name=class_name,
             )
             modular_name = f"{module_name}.{field_name}" if module_name else field_name
 
@@ -1188,7 +1195,10 @@ def parse_object(
         class_name = reference.name
         self.set_title(reference.path, obj)
         fields = self.parse_object_fields(
-            obj, path, get_module_name(class_name, None, treat_dot_as_module=self.treat_dot_as_module)
+            obj,
+            path,
+            get_module_name(class_name, None, treat_dot_as_module=self.treat_dot_as_module),
+            class_name=class_name,
         )
         if fields or not isinstance(obj.additionalProperties, JsonSchemaObject):
             data_model_type_class = self.data_model_type

src/datamodel_code_generator/parser/openapi.py

@@ -393,9 +393,10 @@ def parse_object_fields(
         obj: JsonSchemaObject,
         path: list[str],
         module_name: Optional[str] = None,  # noqa: UP045
+        class_name: Optional[str] = None,  # noqa: UP045
     ) -> list[DataModelFieldBase]:
         """Parse object fields, adding discriminator info for allOf polymorphism."""
-        fields = super().parse_object_fields(obj, path, module_name)
+        fields = super().parse_object_fields(obj, path, module_name, class_name=class_name)
         properties = obj.properties or {}
 
         result_fields: list[DataModelFieldBase] = []
@@ -550,7 +551,9 @@ def parse_all_parameters(
                 raise Exception(msg)  # noqa: TRY002
 
             field_name, alias = self.model_resolver.get_valid_field_name_and_alias(
-                field_name=parameter_name, excludes=exclude_field_names
+                field_name=parameter_name,
+                excludes=exclude_field_names,
+                class_name=name,
             )
             if parameter.schema_:
                 fields.append(

src/datamodel_code_generator/reference.py

@@ -283,11 +283,33 @@ def get_valid_name(  # noqa: PLR0912
         return new_name
 
     def get_valid_field_name_and_alias(
-        self, field_name: str, excludes: set[str] | None = None
+        self,
+        field_name: str,
+        excludes: set[str] | None = None,
+        path: list[str] | None = None,
+        class_name: str | None = None,
     ) -> tuple[str, str | None]:
-        """Get valid field name and original alias if different."""
+        """Get valid field name and original alias if different.
+
+        Supports hierarchical alias resolution with the following priority:
+        1. Scoped aliases (ClassName.field_name) - class-level specificity
+        2. Flat aliases (field_name) - applies to all occurrences
+
+        Args:
+            field_name: The original field name from the schema.
+            excludes: Set of names to avoid when generating valid names.
+            path: Unused, kept for backward compatibility.
+            class_name: Optional class name for scoped alias resolution.
+        """
+        del path
+        if class_name:
+            scoped_key = f"{class_name}.{field_name}"
+            if scoped_key in self.aliases:
+                return self.aliases[scoped_key], field_name
+
         if field_name in self.aliases:
             return self.aliases[field_name], field_name
+
         valid_name = self.get_valid_name(field_name, excludes=excludes)
         return (
             valid_name,
@@ -767,9 +789,25 @@ def get_valid_field_name_and_alias(
         field_name: str,
         excludes: set[str] | None = None,
         model_type: ModelType = ModelType.PYDANTIC,
+        path: list[str] | None = None,
+        class_name: str | None = None,
     ) -> tuple[str, str | None]:
-        """Get a valid field name and alias for the specified model type."""
-        return self.field_name_resolvers[model_type].get_valid_field_name_and_alias(field_name, excludes)
+        """Get a valid field name and alias for the specified model type.
+
+        Args:
+            field_name: The original field name from the schema.
+            excludes: Set of names to avoid when generating valid names.
+            model_type: The type of model (PYDANTIC, ENUM, or CLASS).
+            path: Unused, kept for backward compatibility.
+            class_name: Optional class name for scoped alias resolution.
+
+        Returns:
+            A tuple of (valid_field_name, alias_or_none).
+        """
+        del path
+        return self.field_name_resolvers[model_type].get_valid_field_name_and_alias(
+            field_name, excludes, class_name=class_name
+        )
 
 
 def _get_inflect_engine() -> inflect.engine:

tests/data/aliases/hierarchical_aliases_scoped.json

@@ -0,0 +1,5 @@
+{
+  "Root.name": "root_name",
+  "User.name": "user_name",
+  "Address.name": "address_name"
+}

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

@@ -0,0 +1,25 @@
+# generated by datamodel-codegen:
+#   filename:  hierarchical_aliases.json
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class User(BaseModel):
+    user_name: Optional[str] = Field(None, alias='name')
+    id: Optional[int] = None
+
+
+class Address(BaseModel):
+    address_name: Optional[str] = Field(None, alias='name')
+    city: Optional[str] = None
+
+
+class Root(BaseModel):
+    root_name: Optional[str] = Field(None, alias='name')
+    user: Optional[User] = Field(None, title='User')
+    address: Optional[Address] = Field(None, title='Address')