Add support for prefixItems to emit tuples (#2537)

* Add support for prefixItems to emit tuples

* Refactor test for prefix items handling to use helper function for improved readability

* feat: Enhance JSON Schema support with prefixItems and tuple validation examples

* fix docs

* fix: check items is None or False for tuple detection

* style: use set literal for membership test

* fix: avoid mutating input object, suppress constraints in get_object_field

* docs: Update examples to use modern Python 3.10+ type hint syntax

- Replace Optional[X] with X | None
- Replace List[X] with list[X]
- Replace Tuple[X] with tuple[X]
- Update Pydantic v1 examples to v2 syntax (RootModel instead of __root__)

---------

Co-authored-by: Koudai Aono <koxudaxi@gmail.com>
Co-authored-by: Antonio Spadaro <ilovelinux@users.noreply.github.com>

Author: 3 people

docs/cli-reference/general-options.md

@@ -1216,21 +1216,21 @@ and generated code stay in sync. Works with both single files and directory outp
     ```python
     # generated by datamodel-codegen:
     #   filename:  person.json
-    
+
     from __future__ import annotations
-    
-    from typing import Any, List, Optional
-    
+
+    from typing import Any
+
     from pydantic import BaseModel, Field, conint
-    
-    
+
+
     class Person(BaseModel):
-        firstName: Optional[str] = Field(None, description="The person's first name.")
-        lastName: Optional[str] = Field(None, description="The person's last name.")
-        age: Optional[conint(ge=0)] = Field(
+        firstName: str | None = Field(None, description="The person's first name.")
+        lastName: str | None = Field(None, description="The person's last name.")
+        age: conint(ge=0) | None = Field(
             None, description='Age in years which must be equal to or greater than zero.'
         )
-        friends: Optional[List[Any]] = None
+        friends: list[Any] | None = None
         comment: None = None
     ```
 

docs/graphql.md

@@ -54,7 +54,7 @@ type Query {
 
 from __future__ import annotations
 
-from typing import List, Optional, TypeAlias
+from typing import TypeAlias
 
 from pydantic import BaseModel, Field
 from typing_extensions import Literal
@@ -72,29 +72,29 @@ String: TypeAlias = str
 
 
 class Author(BaseModel):
-    books: Optional[List[Optional[Book]]] = Field(default_factory=list)
+    books: list[Book | None] | None = Field(default_factory=list)
     id: ID
-    name: Optional[String] = None
-    typename__: Optional[Literal['Author']] = Field('Author', alias='__typename')
+    name: String | None = None
+    typename__: Literal['Author'] | None = Field('Author', alias='__typename')
 
 
 class Book(BaseModel):
-    author: Optional[Author] = None
+    author: Author | None = None
     id: ID
-    title: Optional[String] = None
-    typename__: Optional[Literal['Book']] = Field('Book', alias='__typename')
+    title: String | None = None
+    typename__: Literal['Book'] | None = Field('Book', alias='__typename')
 
 
 class AuthorBooksInput(BaseModel):
     id: ID
-    typename__: Optional[Literal['AuthorBooksInput']] = Field(
+    typename__: Literal['AuthorBooksInput'] | None = Field(
         'AuthorBooksInput', alias='__typename'
     )
 
 
 class BooksInput(BaseModel):
-    ids: List[ID]
-    typename__: Optional[Literal['BooksInput']] = Field(
+    ids: list[ID]
+    typename__: Literal['BooksInput'] | None = Field(
         'BooksInput', alias='__typename'
     )
 

docs/jsondata.md

@@ -41,19 +41,17 @@ datamodel-codegen --input pets.json --input-file-type json --output model.py
 
 from __future__ import annotations
 
-from typing import List, Optional
-
 from pydantic import BaseModel
 
 
 class Pet(BaseModel):
     name: str
     age: int
-    nickname: Optional[str] = None
+    nickname: str | None = None
 
 
 class Model(BaseModel):
-    pets: List[Pet]
+    pets: list[Pet]
     status: int
 
 ```

docs/jsonschema.md

@@ -49,19 +49,73 @@ datamodel-codegen --input person.json --input-file-type jsonschema --output mode
 
 from __future__ import annotations
 
-from typing import Any, List, Optional
+from typing import Any
 
 from pydantic import BaseModel, Field, conint
 
 
 class Person(BaseModel):
-    firstName: Optional[str] = Field(None, description="The person's first name.")
-    lastName: Optional[str] = Field(None, description="The person's last name.")
-    age: Optional[conint(ge=0)] = Field(
+    firstName: str | None = Field(None, description="The person's first name.")
+    lastName: str | None = Field(None, description="The person's last name.")
+    age: conint(ge=0) | None = Field(
         None, description='Age in years which must be equal to or greater than zero.'
     )
-    friends: Optional[List] = None
-    comment: Optional[Any] = None
+    friends: list | None = None
+    comment: Any | None = None
+```
+
+## Tuple validation
+
+JSON Schema's [`prefixItems`](https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation) syntax lets you describe heterogeneous arrays.
+
+When:
+
+- `prefixItems` is present
+- no `items` are specified
+- `minItems`/`maxItems` match the number of prefix entries
+
+datamodel-code-generator emits precise tuple annotations.
+
+### Example
+
+```json
+{
+  "$defs": {
+    "Span": {
+      "type": "object",
+      "properties": {
+        "value": { "type": "integer" }
+      },
+      "required": ["value"]
+    }
+  },
+  "title": "defaults",
+  "type": "object",
+  "properties": {
+    "a": {
+      "type": "array",
+      "prefixItems": [
+        { "$ref": "#/$defs/Span" },
+        { "type": "string" }
+      ],
+      "minItems": 2,
+      "maxItems": 2
+    }
+  },
+  "required": ["a"]
+}
+```
+
+```py
+from pydantic import BaseModel
+
+
+class Span(BaseModel):
+    value: int
+
+
+class Defaults(BaseModel):
+    a: tuple[Span, str]
 ```
 
 ---

docs/openapi.md

@@ -130,19 +130,17 @@ components:
 
 from __future__ import annotations
 
-from typing import List, Optional
-
-from pydantic import BaseModel
+from pydantic import BaseModel, RootModel
 
 
 class Pet(BaseModel):
     id: int
     name: str
-    tag: Optional[str] = None
+    tag: str | None = None
 
 
-class Pets(BaseModel):
-    __root__: List[Pet]
+class Pets(RootModel[list[Pet]]):
+    root: list[Pet]
 
 
 class Error(BaseModel):

src/datamodel_code_generator/imports.py

@@ -176,6 +176,7 @@ def dump_all(self, *, multiline: bool = False) -> str:
 IMPORT_UNION = Import.from_full_path("typing.Union")
 IMPORT_OPTIONAL = Import.from_full_path("typing.Optional")
 IMPORT_LITERAL = Import.from_full_path("typing.Literal")
+IMPORT_TUPLE = Import.from_full_path("typing.Tuple")
 IMPORT_TYPE_ALIAS = Import.from_full_path("typing.TypeAlias")
 IMPORT_TYPE_ALIAS_TYPE = Import.from_full_path("typing_extensions.TypeAliasType")
 IMPORT_SEQUENCE = Import.from_full_path("typing.Sequence")

src/datamodel_code_generator/parser/jsonschema.py

@@ -310,6 +310,7 @@ def validate_null_type(cls, value: Any) -> Any:  # noqa: N805
         return value
 
     items: Optional[Union[list[JsonSchemaObject], JsonSchemaObject, bool]] = None  # noqa: UP007, UP045
+    prefixItems: Optional[list[JsonSchemaObject]] = None  # noqa: N815, UP045
     uniqueItems: Optional[bool] = None  # noqa: N815, UP045
     type: Optional[Union[str, list[str]]] = None  # noqa: UP007, UP045
     format: Optional[str] = None  # noqa: UP045
@@ -383,7 +384,7 @@ def is_object(self) -> bool:
     @cached_property
     def is_array(self) -> bool:
         """Check if the schema represents an array type."""
-        return self.items is not None or self.type == "array"
+        return self.items is not None or self.prefixItems is not None or self.type == "array"
 
     @cached_property
     def ref_object_name(self) -> str:  # pragma: no cover
@@ -1014,13 +1015,23 @@ def get_object_field(  # noqa: PLR0913
         original_field_name: str | None,
     ) -> DataModelFieldBase:
         """Create a data model field from a JSON Schema object field."""
+        constraints = field.dict() if self.is_constraints_field(field) else None
+        # Suppress minItems/maxItems for fixed-length tuples
+        if (
+            constraints
+            and field.prefixItems is not None
+            and field.minItems == field.maxItems == len(field.prefixItems)
+            and field.items in {None, False}
+        ):
+            constraints.pop("minItems", None)
+            constraints.pop("maxItems", None)
         return self.data_model_field_type(
             name=field_name,
             default=field.default,
             data_type=field_type,
             required=required,
             alias=alias,
-            constraints=field.dict() if self.is_constraints_field(field) else None,
+            constraints=constraints,
             nullable=field.nullable if self.strict_nullable and (field.has_default or required) else None,
             strip_default_none=self.strip_default_none,
             extras=self.get_field_extras(field),
@@ -2366,7 +2377,7 @@ def parse_list_item(
             for index, item in enumerate(target_items)
         ]
 
-    def parse_array_fields(
+    def parse_array_fields(  # noqa: PLR0912
         self,
         name: str,
         obj: JsonSchemaObject,
@@ -2384,13 +2395,23 @@ def parse_array_fields(
             else:
                 required = not obj.nullable and required
                 nullable = None
-        match obj.items:
-            case JsonSchemaObject():
-                items: list[JsonSchemaObject] = [obj.items]
-            case list():
-                items = obj.items
-            case _:
-                items = []
+        is_tuple = False
+        suppress_item_constraints = False
+        if isinstance(obj.items, JsonSchemaObject):
+            items: list[JsonSchemaObject] = [obj.items]
+        elif isinstance(obj.items, list):
+            items = obj.items
+        elif (
+            obj.prefixItems is not None
+            and obj.minItems == obj.maxItems == len(obj.prefixItems)
+            and obj.items in {None, False}
+        ):
+            # Suppress minItems/maxItems constraints for fixed-length tuples
+            suppress_item_constraints = True
+            items = obj.prefixItems
+            is_tuple = True
+        else:
+            items = []
 
         if items:
             item_data_types = self.parse_list_item(
@@ -2406,7 +2427,8 @@ def parse_array_fields(
         data_types: list[DataType] = [
             self.data_type(
                 data_types=item_data_types,
-                is_list=True,
+                is_tuple=is_tuple,
+                is_list=not is_tuple,
             )
         ]
         # TODO: decide special path word for a combined data model.
@@ -2416,11 +2438,15 @@ def parse_array_fields(
             data_types.append(self.parse_object(name, obj, get_special_path("object", path)))
         if obj.enum and not self.ignore_enum_constraints:
             data_types.append(self.parse_enum(name, obj, get_special_path("enum", path)))
+        constraints = obj.dict()
+        if suppress_item_constraints:
+            constraints.pop("minItems", None)
+            constraints.pop("maxItems", None)
         return self.data_model_field_type(
             data_type=self.data_type(data_types=data_types),
             default=obj.default,
             required=required,
-            constraints=obj.dict(),
+            constraints=constraints,
             nullable=nullable,
             strip_default_none=self.strip_default_none,
             extras=self.get_field_extras(obj),
@@ -2921,6 +2947,9 @@ def _traverse_schema_objects(  # noqa: PLR0912
             case list() as items:
                 for item in items:
                     self._traverse_schema_objects(item, path, callback, include_one_of=include_one_of)
+        if obj.prefixItems:
+            for item in obj.prefixItems:
+                self._traverse_schema_objects(item, path, callback, include_one_of=include_one_of)
         if isinstance(obj.additionalProperties, JsonSchemaObject):
             self._traverse_schema_objects(obj.additionalProperties, path, callback, include_one_of=include_one_of)
         if obj.patternProperties:
@@ -2943,10 +2972,32 @@ def _resolve_ref_callback(self, obj: JsonSchemaObject, path: list[str]) -> None:
         if obj.ref:
             self.resolve_ref(obj.ref)
 
-    def _add_id_callback(self, obj: JsonSchemaObject, path: list[str]) -> None:
+    def _add_id_callback(self, obj: JsonSchemaObject, path: list[str]) -> None:  # noqa: PLR0912
         """Add $id to model resolver."""
         if obj.id:
             self.model_resolver.add_id(obj.id, path)
+        if obj.items:
+            if isinstance(obj.items, JsonSchemaObject):
+                self.parse_id(obj.items, path)
+            elif isinstance(obj.items, list):
+                for item in obj.items:
+                    self.parse_id(item, path)
+        if obj.prefixItems:
+            for item in obj.prefixItems:
+                self.parse_id(item, path)
+        if isinstance(obj.additionalProperties, JsonSchemaObject):
+            self.parse_id(obj.additionalProperties, path)
+        if obj.patternProperties:
+            for value in obj.patternProperties.values():
+                self.parse_id(value, path)
+        for item in obj.anyOf:
+            self.parse_id(item, path)
+        for item in obj.allOf:
+            self.parse_id(item, path)
+        if obj.properties:
+            for property_value in obj.properties.values():
+                if isinstance(property_value, JsonSchemaObject):
+                    self.parse_id(property_value, path)
 
     def parse_ref(self, obj: JsonSchemaObject, path: list[str]) -> None:
         """Recursively parse all $ref references in a schema object."""