Add --use-generic-base-class option for DRY model config (#2726)

This option creates a shared base class (BaseModel/Struct) with common
configuration instead of repeating model_config in every generated model.

Features:
- Supports pydantic v2 BaseModel and msgspec Struct
- Works with module split mode (single BaseModel shared across modules)
- Preserves schema inheritance relationships
- Handles circular imports via _internal.py pattern

Author: koxudaxi

docs/cli-reference/index.md

@@ -11,7 +11,7 @@ This documentation is auto-generated from test cases.
 | 📁 [Base Options](base-options.md) | 5 | Input/output configuration |
 | 🔧 [Typing Customization](typing-customization.md) | 17 | Type annotation and import behavior |
 | 🏷️ [Field Customization](field-customization.md) | 20 | Field naming and docstring behavior |
-| 🏗️ [Model Customization](model-customization.md) | 27 | Model generation behavior |
+| 🏗️ [Model Customization](model-customization.md) | 28 | Model generation behavior |
 | 🎨 [Template Customization](template-customization.md) | 16 | Output formatting and custom rendering |
 | 📘 [OpenAPI-only Options](openapi-only-options.md) | 6 | OpenAPI-specific features |
 | ⚙️ [General Options](general-options.md) | 14 | Utilities and meta options |
@@ -167,6 +167,7 @@ This documentation is auto-generated from test cases.
 - [`--use-exact-imports`](template-customization.md#use-exact-imports)
 - [`--use-field-description`](field-customization.md#use-field-description)
 - [`--use-frozen-field`](model-customization.md#use-frozen-field)
+- [`--use-generic-base-class`](model-customization.md#use-generic-base-class)
 - [`--use-generic-container-types`](typing-customization.md#use-generic-container-types)
 - [`--use-inline-field-description`](field-customization.md#use-inline-field-description)
 - [`--use-non-positive-negative-number-constrained-types`](typing-customization.md#use-non-positive-negative-number-constrained-types)

docs/cli-reference/model-customization.md

@@ -28,6 +28,7 @@
 | [`--use-default-factory-for-optional-nested-models`](#use-default-factory-for-optional-nested-models) | Generate default_factory for optional nested model fields. |
 | [`--use-default-kwarg`](#use-default-kwarg) | Use default= keyword argument instead of positional argument... |
 | [`--use-frozen-field`](#use-frozen-field) | Generate frozen (immutable) field definitions for readOnly p... |
+| [`--use-generic-base-class`](#use-generic-base-class) | Generate a shared base class with model configuration to avo... |
 | [`--use-one-literal-as-default`](#use-one-literal-as-default) | Use single literal value as default when enum has only one o... |
 | [`--use-serialize-as-any`](#use-serialize-as-any) | Wrap fields with subtypes in Pydantic's SerializeAsAny. |
 | [`--use-subclass-enum`](#use-subclass-enum) | Generate typed Enum subclasses for enums with specific field... |
@@ -5164,6 +5165,109 @@ The `--use-frozen-field` flag generates frozen field definitions:
 
 ---
 
+## `--use-generic-base-class` {#use-generic-base-class}
+
+Generate a shared base class with model configuration to avoid repetition (DRY).
+
+!!! tip "Usage"
+
+    ```bash
+    datamodel-codegen --input schema.json --extra-fields forbid --output-model-type pydantic_v2.BaseModel --use-generic-base-class # (1)!
+    ```
+
+    1. :material-arrow-left: `--use-generic-base-class` - the option documented here
+
+??? example "Examples"
+
+    **Input Schema:**
+
+    ```json
+    {
+      "title": "Test",
+      "type": "object",
+      "required": [
+        "foo"
+      ],
+      "properties": {
+        "foo": {
+          "type": "object",
+          "properties": {
+            "x": {
+              "type": "integer"
+            }
+          },
+          "additionalProperties": true
+        },
+        "bar": {
+          "type": "object",
+          "properties": {
+            "y": {
+              "type": "integer"
+            }
+          },
+          "additionalProperties": false
+        },
+        "baz": {
+          "type": "object",
+          "properties": {
+            "z": {
+              "type": "integer"
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+    ```
+
+    **Output:**
+
+    ```python
+    # generated by datamodel-codegen:
+    #   filename:  extra_fields.json
+    #   timestamp: 2019-07-26T00:00:00+00:00
+    
+    from __future__ import annotations
+    
+    from pydantic import BaseModel as _BaseModel
+    from pydantic import ConfigDict
+    
+    
+    class BaseModel(_BaseModel):
+        model_config = ConfigDict(
+            extra='forbid',
+        )
+    
+    
+    class Foo(BaseModel):
+        model_config = ConfigDict(
+            extra='allow',
+        )
+        x: int | None = None
+    
+    
+    class Bar(BaseModel):
+        model_config = ConfigDict(
+            extra='forbid',
+        )
+        y: int | None = None
+    
+    
+    class Baz(BaseModel):
+        z: int | None = None
+    
+    
+    class Test(BaseModel):
+        model_config = ConfigDict(
+            extra='forbid',
+        )
+        foo: Foo
+        bar: Bar | None = None
+        baz: Baz | None = None
+    ```
+
+---
+
 ## `--use-one-literal-as-default` {#use-one-literal-as-default}
 
 Use single literal value as default when enum has only one option.

docs/cli-reference/quick-reference.md

@@ -97,6 +97,7 @@ datamodel-codegen [OPTIONS]
 | [`--use-default-factory-for-optional-nested-models`](model-customization.md#use-default-factory-for-optional-nested-models) | Generate default_factory for optional nested model fields. |
 | [`--use-default-kwarg`](model-customization.md#use-default-kwarg) | Use default= keyword argument instead of positional argument for fields with def... |
 | [`--use-frozen-field`](model-customization.md#use-frozen-field) | Generate frozen (immutable) field definitions for readOnly properties. |
+| [`--use-generic-base-class`](model-customization.md#use-generic-base-class) | Generate a shared base class with model configuration to avoid repetition (DRY).... |
 | [`--use-one-literal-as-default`](model-customization.md#use-one-literal-as-default) | Use single literal value as default when enum has only one option. |
 | [`--use-serialize-as-any`](model-customization.md#use-serialize-as-any) | Wrap fields with subtypes in Pydantic's SerializeAsAny. |
 | [`--use-subclass-enum`](model-customization.md#use-subclass-enum) | Generate typed Enum subclasses for enums with specific field types. |
@@ -260,6 +261,7 @@ All options sorted alphabetically:
 - [`--use-exact-imports`](template-customization.md#use-exact-imports) - Import exact types instead of modules.
 - [`--use-field-description`](field-customization.md#use-field-description) - Include schema descriptions as Field docstrings.
 - [`--use-frozen-field`](model-customization.md#use-frozen-field) - Generate frozen (immutable) field definitions for readOnly p...
+- [`--use-generic-base-class`](model-customization.md#use-generic-base-class) - Generate a shared base class with model configuration to avo...
 - [`--use-generic-container-types`](typing-customization.md#use-generic-container-types) - Use typing.Dict/List instead of dict/list for container type...
 - [`--use-inline-field-description`](field-customization.md#use-inline-field-description) - Add field descriptions as inline comments.
 - [`--use-non-positive-negative-number-constrained-types`](typing-customization.md#use-non-positive-negative-number-constrained-types) - Use NonPositive/NonNegative types for number constraints.

src/datamodel_code_generator/__init__.py

@@ -403,6 +403,7 @@ def generate(  # noqa: PLR0912, PLR0913, PLR0914, PLR0915
     allow_population_by_field_name: bool = False,
     allow_extra_fields: bool = False,
     extra_fields: str | None = None,
+    use_generic_base_class: bool = False,
     apply_default_values_for_required_fields: bool = False,
     force_optional_for_required_fields: bool = False,
     class_name: str | None = None,
@@ -650,6 +651,7 @@ def get_header_and_first_line(csv_file: IO[str]) -> dict[str, Any]:
         allow_population_by_field_name=allow_population_by_field_name,
         allow_extra_fields=allow_extra_fields,
         extra_fields=extra_fields,
+        use_generic_base_class=use_generic_base_class,
         apply_default_values_for_required_fields=apply_default_values_for_required_fields,
         force_optional_for_required_fields=force_optional_for_required_fields,
         class_name=class_name,

src/datamodel_code_generator/__main__.py

@@ -391,6 +391,7 @@ def validate_all_exports_collision_strategy(cls, values: dict[str, Any]) -> dict
     allow_population_by_field_name: bool = False
     allow_extra_fields: bool = False
     extra_fields: Optional[str] = None  # noqa: UP045
+    use_generic_base_class: bool = False
     use_default: bool = False
     force_optional: bool = False
     class_name: Optional[str] = None  # noqa: UP045
@@ -696,6 +697,7 @@ def run_generate_from_config(  # noqa: PLR0913, PLR0917
         allow_population_by_field_name=config.allow_population_by_field_name,
         allow_extra_fields=config.allow_extra_fields,
         extra_fields=config.extra_fields,
+        use_generic_base_class=config.use_generic_base_class,
         apply_default_values_for_required_fields=config.use_default,
         force_optional_for_required_fields=config.force_optional,
         class_name=config.class_name,

src/datamodel_code_generator/arguments.py

@@ -269,6 +269,13 @@ def start_section(self, heading: str | None) -> None:
     action="store_true",
     default=None,
 )
+model_options.add_argument(
+    "--use-generic-base-class",
+    help="Generate a shared base class with model configuration (e.g., extra='forbid') "
+    "instead of repeating the configuration in each model. Keeps code DRY.",
+    action="store_true",
+    default=None,
+)
 model_options.add_argument(
     "--use-schema-description",
     help="Use schema description to populate class docstring",

src/datamodel_code_generator/cli_options.py

@@ -100,6 +100,7 @@ class CLIOptionMeta:
     "--use-one-literal-as-default": CLIOptionMeta(name="--use-one-literal-as-default", category=OptionCategory.MODEL),
     "--use-serialize-as-any": CLIOptionMeta(name="--use-serialize-as-any", category=OptionCategory.MODEL),
     "--skip-root-model": CLIOptionMeta(name="--skip-root-model", category=OptionCategory.MODEL),
+    "--use-generic-base-class": CLIOptionMeta(name="--use-generic-base-class", category=OptionCategory.MODEL),
     # ==========================================================================
     # Field Customization
     # ==========================================================================

src/datamodel_code_generator/model/base.py

@@ -49,6 +49,8 @@
 TEMPLATE_DIR: Path = Path(__file__).parents[0] / "template"
 
 ALL_MODEL: str = "#all#"
+GENERIC_BASE_CLASS_PATH: str = "#/__datamodel_code_generator__/generic_base_class__"
+GENERIC_BASE_CLASS_NAME: str = "__generic_base_class__"
 
 
 def repr_set_sorted(value: set[Any]) -> str:
@@ -474,7 +476,8 @@ class DataModel(TemplateBase, Nullable, ABC):  # noqa: PLR0904
     TEMPLATE_FILE_PATH: ClassVar[str] = ""
     BASE_CLASS: ClassVar[str] = ""
     DEFAULT_IMPORTS: ClassVar[tuple[Import, ...]] = ()
-    IS_ALIAS: bool = False
+    IS_ALIAS: ClassVar[bool] = False
+    SUPPORTS_GENERIC_BASE_CLASS: ClassVar[bool] = True
     has_forward_reference: bool = False
 
     def __init__(  # noqa: PLR0913
@@ -707,6 +710,22 @@ def is_alias(self) -> bool:
         """Whether is a type alias (i.e. not an instance of BaseModel/RootModel)."""
         return self.IS_ALIAS
 
+    @classmethod
+    def create_base_class_model(
+        cls,
+        config: dict[str, Any],  # noqa: ARG003
+        reference: Reference,  # noqa: ARG003
+        custom_template_dir: Path | None = None,  # noqa: ARG003
+        keyword_only: bool = False,  # noqa: ARG003, FBT001, FBT002
+        treat_dot_as_module: bool = False,  # noqa: ARG003, FBT001, FBT002
+    ) -> DataModel | None:
+        """Create a shared base class model for DRY configuration.
+
+        Returns the base model or None if not supported. Updates reference in place.
+        Each model type should override this to provide appropriate implementation.
+        """
+        return None
+
     @property
     def nullable(self) -> bool:
         """Check if this model is nullable."""

src/datamodel_code_generator/model/enum.py

@@ -42,6 +42,7 @@ class Enum(DataModel):
     TEMPLATE_FILE_PATH: ClassVar[str] = "Enum.jinja2"
     BASE_CLASS: ClassVar[str] = "enum.Enum"
     DEFAULT_IMPORTS: ClassVar[tuple[Import, ...]] = (IMPORT_ENUM,)
+    SUPPORTS_GENERIC_BASE_CLASS: ClassVar[bool] = False
 
     def __init__(  # noqa: PLR0913
         self,

src/datamodel_code_generator/model/msgspec.py

@@ -20,11 +20,12 @@
     Import,
 )
 from datamodel_code_generator.model import DataModel, DataModelFieldBase
-from datamodel_code_generator.model.base import UNDEFINED
+from datamodel_code_generator.model.base import UNDEFINED, BaseClassDataType
 from datamodel_code_generator.model.imports import (
     IMPORT_MSGSPEC_CONVERT,
     IMPORT_MSGSPEC_FIELD,
     IMPORT_MSGSPEC_META,
+    IMPORT_MSGSPEC_STRUCT,
     IMPORT_MSGSPEC_UNSET,
     IMPORT_MSGSPEC_UNSETTYPE,
 )
@@ -109,7 +110,18 @@ class Struct(DataModel):
 
     TEMPLATE_FILE_PATH: ClassVar[str] = "msgspec.jinja2"
     BASE_CLASS: ClassVar[str] = "msgspec.Struct"
+    BASE_CLASS_NAME: ClassVar[str] = "Struct"
+    BASE_CLASS_ALIAS: ClassVar[str] = "_Struct"
     DEFAULT_IMPORTS: ClassVar[tuple[Import, ...]] = ()
+    CONFIG_MAPPING: ClassVar[dict[tuple[str, Any], tuple[str, Any] | None]] = {
+        ("allow_mutation", False): ("frozen", True),
+        ("extra_fields", "forbid"): ("forbid_unknown_fields", True),
+        ("extra_fields", "allow"): None,
+        ("extra_fields", "ignore"): None,
+        ("allow_extra_fields", True): None,
+        ("allow_population_by_field_name", True): None,
+        ("use_attribute_docstrings", True): None,
+    }
 
     def __init__(  # noqa: PLR0913
         self,
@@ -154,6 +166,46 @@ def add_base_class_kwarg(self, name: str, value: str) -> None:
         """Add keyword argument to base class constructor."""
         self.extra_template_data["base_class_kwargs"][name] = value
 
+    @classmethod
+    def create_base_class_model(
+        cls,
+        config: dict[str, Any],
+        reference: Reference,
+        custom_template_dir: Path | None = None,
+        keyword_only: bool = False,  # noqa: FBT001, FBT002
+        treat_dot_as_module: bool = False,  # noqa: FBT001, FBT002
+    ) -> Struct | None:
+        """Create a shared base class model for DRY configuration.
+
+        Creates a Struct that inherits from msgspec.Struct (aliased as _Struct)
+        with the specified configuration. Updates the reference path and name in place.
+        """
+        reference.path = f"#/{cls.BASE_CLASS_NAME}"
+        reference.name = cls.BASE_CLASS_NAME
+
+        base_model = cls(
+            reference=reference,
+            fields=[],
+            custom_template_dir=custom_template_dir,
+            keyword_only=keyword_only,
+            treat_dot_as_module=treat_dot_as_module,
+        )
+
+        base_model.base_classes = [BaseClassDataType(type=cls.BASE_CLASS_ALIAS)]
+
+        for key, value in config.items():
+            mapping_result = cls.CONFIG_MAPPING.get((key, value))
+            if mapping_result is None:
+                continue
+            mapped_key, mapped_value = mapping_result
+            base_model.add_base_class_kwarg(mapped_key, str(mapped_value))
+
+        base_model._additional_imports.append(
+            Import(from_=IMPORT_MSGSPEC_STRUCT.from_, import_=IMPORT_MSGSPEC_STRUCT.import_, alias=cls.BASE_CLASS_ALIAS)
+        )
+
+        return base_model
+
 
 class Constraints(_Constraints):
     """Constraint model for msgspec fields."""