Add --use-frozen-field option for JSON Schema readOnly support (#2650)

koxudaxi · web-flow · commit 8bbc4df60fd7 · 2025-12-11T02:07:06.000+09:00
* Add --use-frozen-field option to support frozen fields in Pydantic models

* Add use_frozen_field parameter to OpenAPI parser initialization
diff --git a/README.md b/README.md
@@ -444,6 +444,8 @@ Field customization:
                         default values.
   --use-field-description
                         Use schema description to populate field docstring
+  --use-frozen-field    Use Field(frozen=True) for readOnly fields (Pydantic v2) or
+                        Field(allow_mutation=False) (Pydantic v1)
   --use-inline-field-description
                         Use schema description to populate field docstring as inline
                         docstring
diff --git a/docs/index.md b/docs/index.md
@@ -436,6 +436,8 @@ Field customization:
                         default values.
   --use-field-description
                         Use schema description to populate field docstring
+  --use-frozen-field    Use Field(frozen=True) for readOnly fields (Pydantic v2) or
+                        Field(allow_mutation=False) (Pydantic v1)
   --use-inline-field-description
                         Use schema description to populate field docstring as inline
                         docstring
diff --git a/src/datamodel_code_generator/__init__.py b/src/datamodel_code_generator/__init__.py
@@ -443,6 +443,7 @@ def generate(  # noqa: PLR0912, PLR0913, PLR0914, PLR0915
     keyword_only: bool = False,
     frozen_dataclasses: bool = False,
     no_alias: bool = False,
+    use_frozen_field: bool = False,
     formatters: list[Formatter] = DEFAULT_FORMATTERS,
     settings_path: Path | None = None,
     parent_scoped_naming: bool = False,
@@ -682,6 +683,7 @@ def get_header_and_first_line(csv_file: IO[str]) -> dict[str, Any]:
         keyword_only=keyword_only,
         frozen_dataclasses=frozen_dataclasses,
         no_alias=no_alias,
+        use_frozen_field=use_frozen_field,
         formatters=formatters,
         encoding=encoding,
         parent_scoped_naming=parent_scoped_naming,
diff --git a/src/datamodel_code_generator/__main__.py b/src/datamodel_code_generator/__main__.py
@@ -449,6 +449,7 @@ def validate_all_exports_collision_strategy(cls, values: dict[str, Any]) -> dict
     frozen_dataclasses: bool = False
     dataclass_arguments: Optional[DataclassArguments] = None  # noqa: UP045
     no_alias: bool = False
+    use_frozen_field: bool = False
     formatters: list[Formatter] = DEFAULT_FORMATTERS
     parent_scoped_naming: bool = False
     disable_future_imports: bool = False
@@ -879,6 +880,7 @@ def main(args: Sequence[str] | None = None) -> Exit:  # noqa: PLR0911, PLR0912,
             keyword_only=config.keyword_only,
             frozen_dataclasses=config.frozen_dataclasses,
             no_alias=config.no_alias,
+            use_frozen_field=config.use_frozen_field,
             formatters=config.formatters,
             settings_path=config.output if config.check else None,
             parent_scoped_naming=config.parent_scoped_naming,
diff --git a/src/datamodel_code_generator/arguments.py b/src/datamodel_code_generator/arguments.py
@@ -548,6 +548,12 @@ def start_section(self, heading: str | None) -> None:
     action="store_true",
     default=None,
 )
+field_options.add_argument(
+    "--use-frozen-field",
+    help="Use Field(frozen=True) for readOnly fields (Pydantic v2) or Field(allow_mutation=False) (Pydantic v1)",
+    action="store_true",
+    default=None,
+)
 
 # ======================================================================================
 # Options for templating output
diff --git a/src/datamodel_code_generator/model/base.py b/src/datamodel_code_generator/model/base.py
@@ -151,6 +151,7 @@ class Config:
     type_has_null: Optional[bool] = None  # noqa: UP045
     read_only: bool = False
     write_only: bool = False
+    use_frozen_field: bool = False
 
     if not TYPE_CHECKING:
         if not PYDANTIC_V2:
diff --git a/src/datamodel_code_generator/model/pydantic/__init__.py b/src/datamodel_code_generator/model/pydantic/__init__.py
@@ -35,6 +35,7 @@ class Config(_BaseModel):
     allow_mutation: Optional[bool] = None  # noqa: UP045
     arbitrary_types_allowed: Optional[bool] = None  # noqa: UP045
     orm_mode: Optional[bool] = None  # noqa: UP045
+    validate_assignment: Optional[bool] = None  # noqa: UP045
 
 
 __all__ = [
diff --git a/src/datamodel_code_generator/model/pydantic/base_model.py b/src/datamodel_code_generator/model/pydantic/base_model.py
@@ -154,6 +154,9 @@ def _process_data_in_str(self, data: dict[str, Any]) -> None:
         if self.const:
             data["const"] = True
 
+        if self.use_frozen_field and self.read_only:
+            data["allow_mutation"] = False
+
     def _process_annotated_field_arguments(self, field_arguments: list[str]) -> list[str]:  # noqa: PLR6301
         return field_arguments
 
@@ -294,7 +297,7 @@ class BaseModel(BaseModelBase):
     TEMPLATE_FILE_PATH: ClassVar[str] = "pydantic/BaseModel.jinja2"
     BASE_CLASS: ClassVar[str] = "pydantic.BaseModel"
 
-    def __init__(  # noqa: PLR0913
+    def __init__(  # noqa: PLR0912, PLR0913
         self,
         *,
         reference: Reference,
@@ -348,6 +351,12 @@ def __init__(  # noqa: PLR0913
         for config_attribute in "allow_population_by_field_name", "allow_mutation":
             if config_attribute in self.extra_template_data:
                 config_parameters[config_attribute] = self.extra_template_data[config_attribute]
+
+        if "validate_assignment" not in config_parameters and any(
+            field.use_frozen_field and field.read_only for field in self.fields
+        ):
+            config_parameters["validate_assignment"] = True
+
         for data_type in self.all_data_types:
             if data_type.is_custom_type:  # pragma: no cover
                 config_parameters["arbitrary_types_allowed"] = True
diff --git a/src/datamodel_code_generator/model/pydantic_v2/base_model.py b/src/datamodel_code_generator/model/pydantic_v2/base_model.py
@@ -136,6 +136,9 @@ def _process_data_in_str(self, data: dict[str, Any]) -> None:
         # unique_items is not supported in pydantic 2.0
         data.pop("unique_items", None)
 
+        if self.use_frozen_field and self.read_only:
+            data["frozen"] = True
+
         if "union_mode" in data:
             if self.data_type.is_union:
                 data["union_mode"] = data.pop("union_mode").value
diff --git a/src/datamodel_code_generator/parser/base.py b/src/datamodel_code_generator/parser/base.py
@@ -567,6 +567,7 @@ def __init__(  # noqa: PLR0913, PLR0915
         keyword_only: bool = False,
         frozen_dataclasses: bool = False,
         no_alias: bool = False,
+        use_frozen_field: bool = False,
         formatters: list[Formatter] = DEFAULT_FORMATTERS,
         parent_scoped_naming: bool = False,
         dataclass_arguments: DataclassArguments | None = None,
@@ -704,6 +705,7 @@ def __init__(  # noqa: PLR0913, PLR0915
         self.formatters: list[Formatter] = formatters
         self.type_mappings: dict[tuple[str, str], str] = Parser._parse_type_mappings(type_mappings)
         self.read_only_write_only_model_type: ReadOnlyWriteOnlyModelType | None = read_only_write_only_model_type
+        self.use_frozen_field: bool = use_frozen_field
 
     @property
     def field_name_model_type(self) -> ModelType:
diff --git a/src/datamodel_code_generator/parser/graphql.py b/src/datamodel_code_generator/parser/graphql.py
@@ -186,6 +186,7 @@ def __init__(  # noqa: PLR0913
         type_mappings: list[str] | None = None,
         read_only_write_only_model_type: ReadOnlyWriteOnlyModelType | None = None,
         use_serialize_as_any: bool = False,
+        use_frozen_field: bool = False,
     ) -> None:
         """Initialize the GraphQL parser with configuration options."""
         super().__init__(
@@ -276,6 +277,7 @@ def __init__(  # noqa: PLR0913
             type_mappings=type_mappings,
             read_only_write_only_model_type=read_only_write_only_model_type,
             use_serialize_as_any=use_serialize_as_any,
+            use_frozen_field=use_frozen_field,
         )
 
         self.data_model_scalar_type = data_model_scalar_type
diff --git a/src/datamodel_code_generator/parser/jsonschema.py b/src/datamodel_code_generator/parser/jsonschema.py
@@ -589,6 +589,7 @@ def __init__(  # noqa: PLR0913
         keyword_only: bool = False,
         frozen_dataclasses: bool = False,
         no_alias: bool = False,
+        use_frozen_field: bool = False,
         formatters: list[Formatter] = DEFAULT_FORMATTERS,
         parent_scoped_naming: bool = False,
         dataclass_arguments: DataclassArguments | None = None,
@@ -680,6 +681,7 @@ def __init__(  # noqa: PLR0913
             keyword_only=keyword_only,
             frozen_dataclasses=frozen_dataclasses,
             no_alias=no_alias,
+            use_frozen_field=use_frozen_field,
             formatters=formatters,
             parent_scoped_naming=parent_scoped_naming,
             dataclass_arguments=dataclass_arguments,
@@ -1011,6 +1013,7 @@ def get_object_field(  # noqa: PLR0913
             type_has_null=field.type_has_null,
             read_only=self._resolve_field_flag(field, "readOnly"),
             write_only=self._resolve_field_flag(field, "writeOnly"),
+            use_frozen_field=self.use_frozen_field,
         )
 
     def get_data_type(self, obj: JsonSchemaObject) -> DataType:
diff --git a/src/datamodel_code_generator/parser/openapi.py b/src/datamodel_code_generator/parser/openapi.py
@@ -268,6 +268,7 @@ def __init__(  # noqa: PLR0913
         dataclass_arguments: DataclassArguments | None = None,
         type_mappings: list[str] | None = None,
         read_only_write_only_model_type: ReadOnlyWriteOnlyModelType | None = None,
+        use_frozen_field: bool = False,
     ) -> None:
         """Initialize the OpenAPI parser with extensive configuration options."""
         target_datetime_class = target_datetime_class or DatetimeClassType.Awaredatetime
@@ -359,6 +360,7 @@ def __init__(  # noqa: PLR0913
             dataclass_arguments=dataclass_arguments,
             type_mappings=type_mappings,
             read_only_write_only_model_type=read_only_write_only_model_type,
+            use_frozen_field=use_frozen_field,
         )
         self.open_api_scopes: list[OpenAPIScope] = openapi_scopes or [OpenAPIScope.Schemas]
         self.include_path_parameters: bool = include_path_parameters
diff --git a/tests/data/expected/main/jsonschema/use_frozen_field_dataclass.py b/tests/data/expected/main/jsonschema/use_frozen_field_dataclass.py
@@ -0,0 +1,16 @@
+# generated by datamodel-codegen:
+#   filename:  use_frozen_field.json
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class User:
+    id: int
+    name: str
+    password: str
+    created_at: Optional[str] = None
diff --git a/tests/data/expected/main/jsonschema/use_frozen_field_no_readonly.py b/tests/data/expected/main/jsonschema/use_frozen_field_no_readonly.py
@@ -0,0 +1,25 @@
+# generated by datamodel-codegen:
+#   filename:  user.json
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from pydantic import BaseModel, Field, RootModel
+
+
+class Model(RootModel[Any]):
+    root: Any
+
+
+class User(BaseModel):
+    name: Optional[str] = Field(None, examples=['ken'])
+    pets: List[User] = Field(default_factory=list)
+
+
+class Pet(BaseModel):
+    name: Optional[str] = Field(None, examples=['dog', 'cat'])
+
+
+User.model_rebuild()
diff --git a/tests/data/expected/main/jsonschema/use_frozen_field_v1.py b/tests/data/expected/main/jsonschema/use_frozen_field_v1.py
@@ -0,0 +1,20 @@
+# generated by datamodel-codegen:
+#   filename:  use_frozen_field.json
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class User(BaseModel):
+    class Config:
+        validate_assignment = True
+
+    id: int = Field(..., allow_mutation=False, description='Server-generated ID')
+    name: str
+    password: str = Field(..., description='User password')
+    created_at: Optional[datetime] = Field(None, allow_mutation=False)
diff --git a/tests/data/expected/main/jsonschema/use_frozen_field_v2.py b/tests/data/expected/main/jsonschema/use_frozen_field_v2.py
@@ -0,0 +1,16 @@
+# generated by datamodel-codegen:
+#   filename:  use_frozen_field.json
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import AwareDatetime, BaseModel, Field
+
+
+class User(BaseModel):
+    id: int = Field(..., description='Server-generated ID', frozen=True)
+    name: str
+    password: str = Field(..., description='User password')
+    created_at: Optional[AwareDatetime] = Field(None, frozen=True)
diff --git a/tests/data/jsonschema/use_frozen_field.json b/tests/data/jsonschema/use_frozen_field.json
@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "User",
+  "type": "object",
+  "required": ["id", "name", "password"],
+  "properties": {
+    "id": {
+      "type": "integer",
+      "description": "Server-generated ID",
+      "readOnly": true
+    },
+    "name": {
+      "type": "string"
+    },
+    "password": {
+      "type": "string",
+      "description": "User password",
+      "writeOnly": true
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time",
+      "readOnly": true
+    }
+  }
+}
diff --git a/tests/main/jsonschema/test_main_jsonschema.py b/tests/main/jsonschema/test_main_jsonschema.py
@@ -3705,3 +3705,73 @@ def test_main_bundled_schema_with_id_url(mocker: MockerFixture, output_file: Pat
         follow_redirects=True,
         params=None,
     )
+
+
+@pytest.mark.benchmark
+@LEGACY_BLACK_SKIP
+def test_main_use_frozen_field_pydantic_v2(output_file: Path) -> None:
+    """Test --use-frozen-field with Pydantic v2 generates Field(frozen=True) for readOnly fields."""
+    run_main_and_assert(
+        input_path=JSON_SCHEMA_DATA_PATH / "use_frozen_field.json",
+        output_path=output_file,
+        input_file_type="jsonschema",
+        assert_func=assert_file_content,
+        expected_file="use_frozen_field_v2.py",
+        extra_args=[
+            "--output-model-type",
+            "pydantic_v2.BaseModel",
+            "--use-frozen-field",
+        ],
+    )
+
+
+@pytest.mark.benchmark
+def test_main_use_frozen_field_pydantic_v1(output_file: Path) -> None:
+    """Test --use-frozen-field with Pydantic v1 generates Field(allow_mutation=False) for readOnly fields."""
+    run_main_and_assert(
+        input_path=JSON_SCHEMA_DATA_PATH / "use_frozen_field.json",
+        output_path=output_file,
+        input_file_type="jsonschema",
+        assert_func=assert_file_content,
+        expected_file="use_frozen_field_v1.py",
+        extra_args=[
+            "--output-model-type",
+            "pydantic.BaseModel",
+            "--use-frozen-field",
+        ],
+    )
+
+
+@pytest.mark.benchmark
+@LEGACY_BLACK_SKIP
+def test_main_use_frozen_field_no_readonly(output_file: Path) -> None:
+    """Test --use-frozen-field with no readOnly fields produces no frozen fields."""
+    run_main_and_assert(
+        input_path=JSON_SCHEMA_DATA_PATH / "user.json",  # Has no readOnly fields
+        output_path=output_file,
+        input_file_type="jsonschema",
+        assert_func=assert_file_content,
+        expected_file="use_frozen_field_no_readonly.py",
+        extra_args=[
+            "--output-model-type",
+            "pydantic_v2.BaseModel",
+            "--use-frozen-field",
+        ],
+    )
+
+
+@pytest.mark.benchmark
+def test_main_use_frozen_field_dataclass(output_file: Path) -> None:
+    """Test --use-frozen-field with dataclass silently ignores (no error, no frozen)."""
+    run_main_and_assert(
+        input_path=JSON_SCHEMA_DATA_PATH / "use_frozen_field.json",
+        output_path=output_file,
+        input_file_type="jsonschema",
+        assert_func=assert_file_content,
+        expected_file="use_frozen_field_dataclass.py",
+        extra_args=[
+            "--output-model-type",
+            "dataclasses.dataclass",
+            "--use-frozen-field",
+        ],
+    )
