django-ninja-aio-crud 2.17.0__py3-none-any.whl → 2.18.1__py3-none-any.whl

ninja_aio/models/serializers.py

@@ -11,6 +11,8 @@ from typing import (
 )
 import warnings
 import sys
+import threading
+from functools import lru_cache
 
 from django.conf import settings
 from ninja import Schema
@@ -25,6 +27,7 @@ from django.db.models.fields.related_descriptors import (
     ForwardOneToOneDescriptor,
 )
 from pydantic import BeforeValidator, Field
+from pydantic._internal._decorators import PydanticDescriptorProxy
 
 from ninja_aio.types import (
     S_TYPES,
@@ -102,14 +105,166 @@ class BaseSerializer:
         queryset_request = ModelQuerySetSchema()
         extras: list[ModelQuerySetExtraSchema] = []
 
+    # Thread-local storage for tracking circular reference resolution
+    _resolution_context = threading.local()
+
+    @classmethod
+    def _get_resolution_stack(cls) -> list[str]:
+        """
+        Get the current resolution stack for detecting circular references.
+
+        Returns
+        -------
+        list[str]
+            Stack of model names currently being resolved (thread-safe).
+        """
+        if not hasattr(cls._resolution_context, 'stack'):
+            cls._resolution_context.stack = []
+        return cls._resolution_context.stack
+
+    @classmethod
+    def _is_circular_reference(cls, model: models.Model) -> bool:
+        """
+        Check if resolving this model would create a circular reference.
+
+        Security: Prevents infinite recursion and stack overflow attacks.
+
+        Parameters
+        ----------
+        model : models.Model
+            The model to check
+
+        Returns
+        -------
+        bool
+            True if the model is already being resolved (circular reference detected)
+        """
+        model_key = f"{model._meta.app_label}.{model._meta.model_name}"
+        return model_key in cls._get_resolution_stack()
+
+    @classmethod
+    def _push_resolution(cls, model: models.Model) -> None:
+        """Add a model to the resolution stack."""
+        model_key = f"{model._meta.app_label}.{model._meta.model_name}"
+        cls._get_resolution_stack().append(model_key)
+
+    @classmethod
+    def _pop_resolution(cls) -> None:
+        """Remove the most recent model from the resolution stack."""
+        stack = cls._get_resolution_stack()
+        if stack:
+            stack.pop()
+
+    @classmethod
+    def _collect_validators(cls, source_class) -> dict:
+        """
+        Collect Pydantic validator descriptors from a class.
+
+        Iterates over the class attributes looking for ``PydanticDescriptorProxy``
+        instances (created by ``@field_validator`` and ``@model_validator`` decorators).
+
+        Parameters
+        ----------
+        source_class : type | None
+            The class to scan for validators.
+
+        Returns
+        -------
+        dict
+            Mapping of attribute name to ``PydanticDescriptorProxy`` instance.
+        """
+        validators = {}
+        if source_class is None:
+            return validators
+        for attr_name, attr_value in vars(source_class).items():
+            if isinstance(attr_value, PydanticDescriptorProxy):
+                validators[attr_name] = attr_value
+        return validators
+
+    @classmethod
+    def _apply_validators(cls, schema, validators: dict):
+        """
+        Create a subclass of the given schema with validators attached.
+
+        Pydantic discovers validators via ``PydanticDescriptorProxy`` instances
+        during class creation, so placing them on a subclass is sufficient.
+
+        Parameters
+        ----------
+        schema : Schema | None
+            The base schema class generated by ``create_schema``.
+        validators : dict
+            Mapping of validator names to ``PydanticDescriptorProxy`` instances.
+
+        Returns
+        -------
+        Schema | None
+            A subclass with validators applied, or the original schema if no
+            validators are provided.
+        """
+        if not schema or not validators:
+            return schema
+        return type(schema.__name__, (schema,), validators)
+
+    @classmethod
+    def _get_validators(cls, schema_type: type[SCHEMA_TYPES]) -> dict:
+        """
+        Return collected validators for the given schema type.
+
+        Subclasses must implement this to map schema types to the appropriate
+        validator source class.
+
+        Parameters
+        ----------
+        schema_type : SCHEMA_TYPES
+            One of ``"In"``, ``"Patch"``, ``"Out"``, ``"Detail"``, or ``"Related"``.
+
+        Returns
+        -------
+        dict
+            Mapping of validator names to ``PydanticDescriptorProxy`` instances.
+        """
+        return {}
+
     @classmethod
     def _get_fields(cls, s_type: type[S_TYPES], f_type: type[F_TYPES]):
-        # Subclasses provide implementation.
+        """
+        Return raw configuration list for the given serializer/field category.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type (``"create"`` | ``"update"`` | ``"read"`` | ``"detail"``).
+        f_type : F_TYPES
+            Field category (``"fields"`` | ``"optionals"`` | ``"customs"`` | ``"excludes"``).
+
+        Returns
+        -------
+        list
+            Raw configuration list for the requested category.
+
+        Raises
+        ------
+        NotImplementedError
+            Subclasses must provide an implementation.
+        """
         raise NotImplementedError
 
     @classmethod
     def _get_model(cls) -> models.Model:
-        # Subclasses provide implementation.
+        """
+        Return the Django model class associated with this serializer.
+
+        Returns
+        -------
+        models.Model
+            The Django model class.
+
+        Raises
+        ------
+        NotImplementedError
+            Subclasses must provide an implementation.
+        """
         raise NotImplementedError
 
     @classmethod
@@ -246,12 +401,32 @@ class BaseSerializer:
 
     @classmethod
     def _get_relations_serializers(cls) -> dict[str, "Serializer"]:
-        # Optional in subclasses. Default to no explicit relation serializers.
+        """
+        Return mapping of relation field names to their serializer classes.
+
+        Subclasses may override to provide explicit serializer mappings for
+        relation fields used during read schema generation.
+
+        Returns
+        -------
+        dict[str, Serializer]
+            Mapping of field name to serializer class. Empty by default.
+        """
         return {}
 
     @classmethod
     def _get_relations_as_id(cls) -> list[str]:
-        # Optional in subclasses. Default to no relations as ID.
+        """
+        Return relation field names that should be serialized as IDs.
+
+        Subclasses may override to specify which relation fields should be
+        represented as primary key values instead of nested objects.
+
+        Returns
+        -------
+        list[str]
+            Field names to serialize as IDs. Empty by default.
+        """
         return []
 
     @classmethod
@@ -302,45 +477,100 @@ class BaseSerializer:
         -------
         Schema | Union[Schema, ...] | None
             Generated schema, Union of schemas, or None if cannot be resolved.
-        """
-        # Auto-resolve ModelSerializer with readable fields
-        if isinstance(rel_model, ModelSerializerMeta):
-            has_readable_fields = rel_model.get_fields(
-                "read"
-            ) or rel_model.get_custom_fields("read")
-            return rel_model.generate_related_s() if has_readable_fields else None
-
-        # Resolve from explicit serializer mapping
-        rel_serializers = cls._get_relations_serializers() or {}
-        serializer_ref = rel_serializers.get(field_name)
 
-        if not serializer_ref:
+        Notes
+        -----
+        Includes circular reference detection to prevent infinite recursion.
+        """
+        # Security: Check for circular references to prevent infinite recursion
+        if cls._is_circular_reference(rel_model):
+            # Circular reference detected - return None to break the cycle
+            warnings.warn(
+                f"Circular reference detected for {rel_model._meta.label} "
+                f"in field '{field_name}' of {cls._get_model()._meta.label}. "
+                f"Skipping nested schema generation to prevent infinite recursion.",
+                UserWarning,
+                stacklevel=2
+            )
             return None
 
-        resolved = cls._resolve_serializer_reference(serializer_ref)
+        # Track this model in the resolution stack
+        cls._push_resolution(rel_model)
+        try:
+            # Auto-resolve ModelSerializer with readable fields
+            if isinstance(rel_model, ModelSerializerMeta):
+                has_readable_fields = rel_model.get_fields(
+                    "read"
+                ) or rel_model.get_custom_fields("read")
+                return rel_model.generate_related_s() if has_readable_fields else None
+
+            # Resolve from explicit serializer mapping
+            rel_serializers = cls._get_relations_serializers() or {}
+            serializer_ref = rel_serializers.get(field_name)
+
+            if not serializer_ref:
+                return None
+
+            resolved = cls._resolve_serializer_reference(serializer_ref)
 
-        # Handle Union of serializers
-        if get_origin(resolved) is Union:
-            return cls._generate_union_schema(resolved)
+            # Handle Union of serializers
+            if get_origin(resolved) is Union:
+                return cls._generate_union_schema(resolved)
 
-        # Handle single serializer
-        return resolved.generate_related_s()
+            # Handle single serializer
+            return resolved.generate_related_s()
+        finally:
+            # Always pop from resolution stack when done
+            cls._pop_resolution()
 
     @classmethod
     def _is_special_field(
         cls, s_type: type[S_TYPES], field: str, f_type: type[F_TYPES]
     ) -> bool:
-        """Return True if field appears in the given category for s_type."""
+        """
+        Check whether a field appears in the given category for a serializer type.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type (``"create"`` | ``"update"`` | ``"read"`` | ``"detail"``).
+        field : str
+            The field name to look up.
+        f_type : F_TYPES
+            Field category (``"fields"`` | ``"optionals"`` | ``"customs"`` | ``"excludes"``).
+
+        Returns
+        -------
+        bool
+            ``True`` if the field is found in the specified category.
+        """
         special_fields = cls._get_fields(s_type, f_type)
         return any(field in special_f for special_f in special_fields)
 
     @classmethod
     def get_custom_fields(cls, s_type: type[S_TYPES]) -> list[tuple[str, type, Any]]:
         """
-        Normalize declared custom field specs into (name, py_type, default).
+        Normalize declared custom field specs into ``(name, py_type, default)`` tuples.
+
         Accepted tuple shapes:
-        - (name, py_type, default)
-        - (name, py_type) -> default Ellipsis (required)
+
+        - ``(name, py_type, default)`` -- field with explicit default.
+        - ``(name, py_type)`` -- required field (default set to ``Ellipsis``).
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type whose custom fields to retrieve.
+
+        Returns
+        -------
+        list[tuple[str, type, Any]]
+            Normalized list of ``(name, type, default)`` tuples.
+
+        Raises
+        ------
+        ValueError
+            If a custom field spec is not a tuple or has an invalid length.
         """
         raw_customs = cls._get_fields(s_type, "customs") or []
         normalized: list[tuple[str, Any, Any]] = []
@@ -362,7 +592,19 @@ class BaseSerializer:
 
     @classmethod
     def get_optional_fields(cls, s_type: type[S_TYPES]):
-        """Return optional field specs normalized to (name, type, None)."""
+        """
+        Return optional field specs normalized to ``(name, type, None)`` tuples.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type whose optional fields to retrieve.
+
+        Returns
+        -------
+        list[tuple[str, type, None]]
+            Normalized list where each entry defaults to ``None``.
+        """
         return [
             (field, field_type, None)
             for field, field_type in cls._get_fields(s_type, "optionals")
@@ -370,12 +612,39 @@ class BaseSerializer:
 
     @classmethod
     def get_excluded_fields(cls, s_type: S_TYPES):
-        """Return excluded field names for the serializer type."""
+        """
+        Return excluded field names for the given serializer type.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type whose exclusions to retrieve.
+
+        Returns
+        -------
+        list[str]
+            Field names excluded from schema generation.
+        """
         return cls._get_fields(s_type, "excludes")
 
     @classmethod
     def get_fields(cls, s_type: S_TYPES):
-        """Return explicit declared field names for the serializer type (excludes inline customs)."""
+        """
+        Return explicit declared field names for the serializer type.
+
+        Filters out inline custom field tuples from the fields list, returning
+        only string field names.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type whose fields to retrieve.
+
+        Returns
+        -------
+        list[str]
+            Model field names (excludes inline custom tuples).
+        """
         fields = cls._get_fields(s_type, "fields")
         # Filter out inline custom field tuples, return only string field names
         return [f for f in fields if isinstance(f, str)]
@@ -411,14 +680,40 @@ class BaseSerializer:
 
     @classmethod
     def is_custom(cls, field: str) -> bool:
-        """True if field is declared as a custom input in create or update."""
+        """
+        Check if a field is declared as a custom input in create or update.
+
+        Parameters
+        ----------
+        field : str
+            The field name to check.
+
+        Returns
+        -------
+        bool
+            ``True`` if the field appears in the customs category for either
+            ``create`` or ``update`` serializer types.
+        """
         return cls._is_special_field(
             "create", field, "customs"
         ) or cls._is_special_field("update", field, "customs")
 
     @classmethod
     def is_optional(cls, field: str) -> bool:
-        """True if field is declared as optional in create or update."""
+        """
+        Check if a field is declared as optional in create or update.
+
+        Parameters
+        ----------
+        field : str
+            The field name to check.
+
+        Returns
+        -------
+        bool
+            ``True`` if the field appears in the optionals category for either
+            ``create`` or ``update`` serializer types.
+        """
         return cls._is_special_field(
             "create", field, "optionals"
         ) or cls._is_special_field("update", field, "optionals")
@@ -531,7 +826,20 @@ class BaseSerializer:
 
     @classmethod
     def _is_reverse_relation(cls, field_obj) -> bool:
-        """Check if field is a reverse relation (M2M, reverse FK, reverse O2O)."""
+        """
+        Check if a field descriptor represents a reverse relation.
+
+        Parameters
+        ----------
+        field_obj : Any
+            Django model field descriptor.
+
+        Returns
+        -------
+        bool
+            ``True`` if the descriptor is a ``ManyToManyDescriptor``,
+            ``ReverseManyToOneDescriptor``, or ``ReverseOneToOneDescriptor``.
+        """
         return isinstance(
             field_obj,
             (
@@ -543,14 +851,39 @@ class BaseSerializer:
 
     @classmethod
     def _is_forward_relation(cls, field_obj) -> bool:
-        """Check if field is a forward relation (FK, O2O)."""
+        """
+        Check if a field descriptor represents a forward relation.
+
+        Parameters
+        ----------
+        field_obj : Any
+            Django model field descriptor.
+
+        Returns
+        -------
+        bool
+            ``True`` if the descriptor is a ``ForwardOneToOneDescriptor``
+            or ``ForwardManyToOneDescriptor``.
+        """
         return isinstance(
             field_obj, (ForwardOneToOneDescriptor, ForwardManyToOneDescriptor)
         )
 
     @classmethod
     def _warn_missing_relation_serializer(cls, field_name: str, model) -> None:
-        """Emit warning for reverse relations without explicit serializer mapping."""
+        """
+        Emit a warning for reverse relations without an explicit serializer mapping.
+
+        Only warns when the related model is not a ``ModelSerializer`` and the
+        ``NINJA_AIO_RAISE_SERIALIZATION_WARNINGS`` setting is enabled (default).
+
+        Parameters
+        ----------
+        field_name : str
+            Name of the reverse relation field.
+        model : type
+            The Django model class owning the field.
+        """
         if not isinstance(model, ModelSerializerMeta) and getattr(
             settings, "NINJA_AIO_RAISE_SERIALIZATION_WARNINGS", True
         ):
@@ -669,53 +1002,50 @@ class BaseSerializer:
         )
 
     @classmethod
-    def _generate_model_schema(
-        cls,
-        schema_type: type[SCHEMA_TYPES],
-        depth: int = None,
-    ) -> Schema:
-        """
-        Core schema factory bridging configuration to ninja.orm.create_schema.
-        Handles In/Patch/Out/Related.
-        """
-        model = cls._get_model()
-
-        # Handle special schema types with custom logic
-        if schema_type == "Out" or schema_type == "Detail":
-            fields, reverse_rels, excludes, customs, optionals = (
-                cls.get_schema_out_data(schema_type)
-            )
-            if not any([fields, reverse_rels, excludes, customs]):
-                return None
-            schema_name = "SchemaOut" if schema_type == "Out" else "DetailSchemaOut"
-            return create_schema(
-                model=model,
-                name=f"{model._meta.model_name}{schema_name}",
-                depth=depth,
-                fields=fields,
-                custom_fields=reverse_rels + customs + optionals,
-                exclude=excludes,
-            )
+    def _create_out_or_detail_schema(
+        cls, schema_type: type[SCHEMA_TYPES], model, validators, depth: int = None
+    ) -> Schema | None:
+        """Create schema for Out or Detail types."""
+        fields, reverse_rels, excludes, customs, optionals = (
+            cls.get_schema_out_data(schema_type)
+        )
+        if not any([fields, reverse_rels, excludes, customs]):
+            return None
+        schema_name = "SchemaOut" if schema_type == "Out" else "DetailSchemaOut"
+        schema = create_schema(
+            model=model,
+            name=f"{model._meta.model_name}{schema_name}",
+            depth=depth,
+            fields=fields,
+            custom_fields=reverse_rels + customs + optionals,
+            exclude=excludes,
+        )
+        return cls._apply_validators(schema, validators)
 
-        if schema_type == "Related":
-            fields, customs = cls.get_related_schema_data()
-            if not fields and not customs:
-                return None
-            return create_schema(
-                model=model,
-                name=f"{model._meta.model_name}SchemaRelated",
-                fields=fields,
-                custom_fields=customs,
-            )
+    @classmethod
+    def _create_related_schema(cls, model, validators) -> Schema | None:
+        """Create schema for Related type."""
+        fields, customs = cls.get_related_schema_data()
+        if not fields and not customs:
+            return None
+        schema = create_schema(
+            model=model,
+            name=f"{model._meta.model_name}SchemaRelated",
+            fields=fields,
+            custom_fields=customs,
+        )
+        return cls._apply_validators(schema, validators)
 
-        # Handle standard In/Patch schema types
+    @classmethod
+    def _create_in_or_patch_schema(
+        cls, schema_type: type[SCHEMA_TYPES], model, validators
+    ) -> Schema | None:
+        """Create schema for In or Patch types."""
         s_type = "create" if schema_type == "In" else "update"
         fields = cls.get_fields(s_type)
         optionals = cls.get_optional_fields(s_type)
         customs = (
-            cls.get_custom_fields(s_type)
-            + optionals
-            + cls.get_inline_customs(s_type)
+            cls.get_custom_fields(s_type) + optionals + cls.get_inline_customs(s_type)
         )
         excludes = cls.get_excluded_fields(s_type)
 
@@ -736,13 +1066,50 @@ class BaseSerializer:
         if not any([fields, customs, excludes]):
             return None
 
-        return create_schema(
+        schema = create_schema(
             model=model,
             name=f"{model._meta.model_name}Schema{schema_type}",
             fields=fields,
             custom_fields=customs,
             exclude=excludes,
         )
+        return cls._apply_validators(schema, validators)
+
+    @classmethod
+    def _generate_model_schema(
+        cls,
+        schema_type: type[SCHEMA_TYPES],
+        depth: int = None,
+    ) -> Schema:
+        """
+        Core schema factory bridging serializer configuration to ``ninja.orm.create_schema``.
+
+        Dispatches to the appropriate field/custom/exclude gathering logic based
+        on the requested schema type and delegates to Django Ninja's
+        ``create_schema`` for the actual Pydantic model construction.
+
+        Parameters
+        ----------
+        schema_type : SCHEMA_TYPES
+            One of ``"In"``, ``"Patch"``, ``"Out"``, ``"Detail"``, or ``"Related"``.
+        depth : int, optional
+            Nesting depth for related model schemas (used by ``Out`` and ``Detail``).
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no fields are configured.
+        """
+        model = cls._get_model()
+        validators = cls._get_validators(schema_type)
+
+        if schema_type in ("Out", "Detail"):
+            return cls._create_out_or_detail_schema(schema_type, model, validators, depth)
+
+        if schema_type == "Related":
+            return cls._create_related_schema(model, validators)
+
+        return cls._create_in_or_patch_schema(schema_type, model, validators)
 
     @classmethod
     def get_related_schema_data(cls):
@@ -779,28 +1146,94 @@ class BaseSerializer:
         return non_relation_fields, customs
 
     @classmethod
+    @lru_cache(maxsize=128)
     def generate_read_s(cls, depth: int = 1) -> Schema:
-        """Generate read (Out) schema."""
+        """
+        Generate the read (Out) schema for list responses.
+
+        Performance: Results are cached per (class, depth) combination.
+
+        Parameters
+        ----------
+        depth : int, optional
+            Nesting depth for related models. Defaults to ``1``.
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no read fields are configured.
+        """
         return cls._generate_model_schema("Out", depth)
 
     @classmethod
+    @lru_cache(maxsize=128)
     def generate_detail_s(cls, depth: int = 1) -> Schema:
-        """Generate detail (single object Out) schema."""
+        """
+        Generate the detail (single-object) read schema.
+
+        Falls back to the standard read schema if no detail-specific
+        configuration is defined.
+
+        Performance: Results are cached per (class, depth) combination.
+
+        Parameters
+        ----------
+        depth : int, optional
+            Nesting depth for related models. Defaults to ``1``.
+
+        Returns
+        -------
+        Schema
+            Generated Pydantic schema (never ``None``; falls back to read schema).
+        """
         return cls._generate_model_schema("Detail", depth) or cls.generate_read_s(depth)
 
     @classmethod
+    @lru_cache(maxsize=128)
     def generate_create_s(cls) -> Schema:
-        """Generate create (In) schema."""
+        """
+        Generate the create (In) schema for input validation.
+
+        Performance: Results are cached per class.
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no create fields are configured.
+        """
         return cls._generate_model_schema("In")
 
     @classmethod
+    @lru_cache(maxsize=128)
     def generate_update_s(cls) -> Schema:
-        """Generate update (Patch) schema."""
+        """
+        Generate the update (Patch) schema for partial updates.
+
+        Performance: Results are cached per class.
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no update fields are configured.
+        """
         return cls._generate_model_schema("Patch")
 
     @classmethod
+    @lru_cache(maxsize=128)
     def generate_related_s(cls) -> Schema:
-        """Generate related (nested) schema."""
+        """
+        Generate the related (nested) schema for embedding in parent schemas.
+
+        Includes only non-relational model fields and custom fields, preventing
+        infinite nesting of related objects.
+
+        Performance: Results are cached per class.
+
+        Returns
+        -------
+        Schema | None
+            Generated Pydantic schema, or ``None`` if no fields are configured.
+        """
         return cls._generate_model_schema("Related")
 
     @classmethod
@@ -861,8 +1294,8 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
             Disallowed model fields on create (e.g., id, timestamps).
         """
 
-        fields: list[str | tuple[str, Any, Any]] = []
-        customs: list[tuple[str, Any, Any]] = []
+        fields: list[str | tuple[str, Any, Any] | tuple[str, Any]] = []
+        customs: list[tuple[str, Any, Any] | tuple[str, Any]] = []
         optionals: list[tuple[str, Any]] = []
         excludes: list[str] = []
 
@@ -883,8 +1316,8 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
             Relation fields to serialize as IDs instead of nested objects.
         """
 
-        fields: list[str | tuple[str, Any, Any]] = []
-        customs: list[tuple[str, Any, Any]] = []
+        fields: list[str | tuple[str, Any, Any] | tuple[str, Any]] = []
+        customs: list[tuple[str, Any, Any] | tuple[str, Any]] = []
         optionals: list[tuple[str, Any]] = []
         excludes: list[str] = []
         relations_as_id: list[str] = []
@@ -904,8 +1337,8 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
             Optional output fields.
         """
 
-        fields: list[str | tuple[str, Any, Any]] = []
-        customs: list[tuple[str, Any, Any]] = []
+        fields: list[str | tuple[str, Any, Any] | tuple[str, Any]] = []
+        customs: list[tuple[str, Any, Any] | tuple[str, Any]] = []
         optionals: list[tuple[str, Any]] = []
         excludes: list[str] = []
 
@@ -937,9 +1370,47 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
         "detail": "DetailSerializer",
     }
 
+    # Schema type to serializer type mapping for validator resolution
+    _SCHEMA_TO_S_TYPE = {
+        "In": "create",
+        "Patch": "update",
+        "Out": "read",
+        "Detail": "detail",
+        "Related": "read",
+    }
+
+    @classmethod
+    def _get_validators(cls, schema_type: type[SCHEMA_TYPES]) -> dict:
+        """
+        Collect validators from the inner serializer class for the given schema type.
+
+        Parameters
+        ----------
+        schema_type : SCHEMA_TYPES
+            One of ``"In"``, ``"Patch"``, ``"Out"``, ``"Detail"``, or ``"Related"``.
+
+        Returns
+        -------
+        dict
+            Mapping of validator names to ``PydanticDescriptorProxy`` instances.
+        """
+        s_type = cls._SCHEMA_TO_S_TYPE.get(schema_type)
+        config_name = cls._SERIALIZER_CONFIG_MAP.get(s_type)
+        config_class = getattr(cls, config_name, None) if config_name else None
+        return cls._collect_validators(config_class)
+
     @classmethod
     def _get_relations_as_id(cls) -> list[str]:
-        """Return relation fields to serialize as IDs instead of nested objects."""
+        """
+        Return relation fields to serialize as primary key values.
+
+        Reads the ``relations_as_id`` attribute from ``ReadSerializer``.
+
+        Returns
+        -------
+        list[str]
+            Field names whose related objects should be serialized as IDs.
+        """
         return getattr(cls.ReadSerializer, "relations_as_id", [])
 
     @classmethod
@@ -970,17 +1441,30 @@ class ModelSerializer(models.Model, BaseSerializer, metaclass=ModelSerializerMet
 
     @classmethod
     def _get_model(cls) -> "ModelSerializer":
-        """Return the model class itself."""
+        """
+        Return the model class itself.
+
+        Since ``ModelSerializer`` is mixed directly into the model, the model
+        class is the serializer class.
+
+        Returns
+        -------
+        ModelSerializer
+            The model/serializer class.
+        """
         return cls
 
     @classmethod
     def verbose_name_path_resolver(cls) -> str:
         """
-        Slugify plural verbose name for URL path segment.
+        Slugify the plural verbose name for use as a URL path segment.
+
+        Replaces spaces with hyphens in the model's ``verbose_name_plural``.
 
         Returns
         -------
         str
+            Hyphen-separated URL-safe path segment.
         """
         return "-".join(cls._meta.verbose_name_plural.split(" "))
 
@@ -1103,14 +1587,16 @@ class SchemaModelConfig(Schema):
         Optional model fields. Type can be any valid type annotation including Union.
     exclude : Optional[List[str]]
         Model fields to exclude.
-    customs : Optional[List[tuple[str, Any, Any]]]
+    customs : Optional[List[tuple[str, Any, Any] | tuple[str, Any]]]
         Custom / synthetic fields. Type can be any valid type annotation including Union.
+        - 2-tuple: (name, type) - required field
+        - 3-tuple: (name, type, default) - optional field with default
     """
 
     fields: Optional[List[str | tuple[str, Any, Any] | tuple[str, Any]]] = None
     optionals: Optional[List[tuple[str, Any]]] = None
     exclude: Optional[List[str]] = None
-    customs: Optional[List[tuple[str, Any, Any]]] = None
+    customs: Optional[List[tuple[str, Any, Any] | tuple[str, Any]]] = None
 
 
 class Serializer(BaseSerializer, metaclass=SerializerMeta):
@@ -1131,6 +1617,15 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         "detail": "detail",
     }
 
+    # Schema type to validators inner class mapping
+    _VALIDATORS_CLASS_MAP = {
+        "In": "CreateValidators",
+        "Patch": "UpdateValidators",
+        "Out": "ReadValidators",
+        "Detail": "DetailValidators",
+        "Related": "ReadValidators",
+    }
+
     def __init_subclass__(cls, **kwargs):
         super().__init_subclass__(**kwargs)
         from ninja_aio.models.utils import ModelUtil
@@ -1150,26 +1645,118 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         relations_serializers: dict[str, "Serializer"] = {}
         relations_as_id: list[str] = []
 
+    def _parse_payload(self, payload: dict[str, Any] | Schema) -> dict[str, Any]:
+        """
+        Parse and return the input payload.
+
+        Can be overridden to implement custom parsing logic.
+
+        Parameters
+        ----------
+        payload : dict | Schema
+            Input data.
+
+        Returns
+        -------
+        dict
+            Parsed payload.
+        """
+        return payload.model_dump() if isinstance(payload, Schema) else payload
+
+    @classmethod
+    def _get_validators(cls, schema_type: type[SCHEMA_TYPES]) -> dict:
+        """
+        Collect validators from the inner validators class for the given schema type.
+
+        Looks for inner classes named ``CreateValidators``, ``ReadValidators``,
+        ``UpdateValidators``, or ``DetailValidators`` on the serializer.
+
+        Parameters
+        ----------
+        schema_type : SCHEMA_TYPES
+            One of ``"In"``, ``"Patch"``, ``"Out"``, ``"Detail"``, or ``"Related"``.
+
+        Returns
+        -------
+        dict
+            Mapping of validator names to ``PydanticDescriptorProxy`` instances.
+        """
+        class_name = cls._VALIDATORS_CLASS_MAP.get(schema_type)
+        validators_class = getattr(cls, class_name, None) if class_name else None
+        return cls._collect_validators(validators_class)
+
     @classmethod
     def _get_relations_as_id(cls) -> list[str]:
+        """
+        Return relation fields to serialize as primary key values.
+
+        Reads the ``relations_as_id`` attribute from ``Meta``.
+
+        Returns
+        -------
+        list[str]
+            Field names whose related objects should be serialized as IDs.
+        """
         relations_as_id = cls._get_meta_data("relations_as_id")
         return relations_as_id or []
 
     @classmethod
     def _get_meta_data(cls, attr_name: str) -> Any:
+        """
+        Retrieve an attribute from the nested ``Meta`` class.
+
+        Parameters
+        ----------
+        attr_name : str
+            Name of the ``Meta`` attribute to look up.
+
+        Returns
+        -------
+        Any
+            The attribute value, or ``None`` if not defined.
+        """
         return getattr(cls.Meta, attr_name, None)
 
     @classmethod
     def _get_model(cls) -> models.Model:
+        """
+        Return the Django model class from ``Meta.model``.
+
+        Returns
+        -------
+        models.Model
+            The validated Django model class.
+        """
         return cls._validate_model()
 
     @classmethod
     def _get_relations_serializers(cls) -> dict[str, "Serializer"]:
+        """
+        Return the explicit relation-to-serializer mapping from ``Meta``.
+
+        Returns
+        -------
+        dict[str, Serializer]
+            Mapping of relation field names to serializer classes.
+        """
         relations_serializers = cls._get_meta_data("relations_serializers")
         return relations_serializers or {}
 
     @classmethod
     def _get_schema_meta(cls, schema_type: str) -> SchemaModelConfig | None:
+        """
+        Retrieve the ``SchemaModelConfig`` for the given schema type.
+
+        Parameters
+        ----------
+        schema_type : str
+            One of ``"in"``, ``"out"``, ``"update"``, or ``"detail"``.
+
+        Returns
+        -------
+        SchemaModelConfig | None
+            The configuration object, or ``None`` if not defined.
+        """
         match schema_type:
             case "in":
                 return cls._get_meta_data("schema_in")
@@ -1184,6 +1771,19 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
 
     @classmethod
     def _validate_model(cls):
+        """
+        Validate and return the model defined in ``Meta.model``.
+
+        Returns
+        -------
+        models.Model
+            The validated Django model class.
+
+        Raises
+        ------
+        ValueError
+            If ``Meta.model`` is not defined or is not a Django model subclass.
+        """
         model = cls._get_meta_data("model")
         if not model:
             raise ValueError("Meta.model must be defined for Serializer.")
@@ -1193,7 +1793,23 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
 
     @classmethod
     def _get_fields(cls, s_type: type[S_TYPES], f_type: type[F_TYPES]):
-        """Internal accessor for raw configuration lists from Meta schemas."""
+        """
+        Return raw configuration list from the Meta schema for the given categories.
+
+        Falls back to the ``out`` schema when ``detail`` is requested but not defined.
+
+        Parameters
+        ----------
+        s_type : S_TYPES
+            Serializer type (``"create"`` | ``"update"`` | ``"read"`` | ``"detail"``).
+        f_type : F_TYPES
+            Field category (``"fields"`` | ``"optionals"`` | ``"customs"`` | ``"excludes"``).
+
+        Returns
+        -------
+        list
+            Raw configuration list, or empty list if not configured.
+        """
         schema_key = cls._SCHEMA_META_MAP.get(s_type)
         if not schema_key:
             return []
@@ -1248,13 +1864,13 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         self.after_save(instance)
         return instance
 
-    async def create(self, payload: dict[str, Any]) -> models.Model:
+    async def create(self, payload: dict[str, Any] | Schema) -> models.Model:
         """
         Create a new model instance from the provided payload.
 
         Parameters
         ----------
-        payload : dict
+        payload : dict | Schema
             Input data.
 
         Returns
@@ -1262,11 +1878,11 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         models.Model
             Created model instance.
         """
-        instance: models.Model = self.model(**payload)
+        instance: models.Model = self.model(**self._parse_payload(payload))
         return await self.save(instance)
 
     async def update(
-        self, instance: models.Model, payload: dict[str, Any]
+        self, instance: models.Model, payload: dict[str, Any] | Schema
     ) -> models.Model:
         """
         Update an existing model instance with the provided payload.
@@ -1275,7 +1891,7 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         ----------
         instance : models.Model
             The model instance to update.
-        payload : dict
+        payload : dict | Schema
             Input data.
 
         Returns
@@ -1283,7 +1899,7 @@ class Serializer(BaseSerializer, metaclass=SerializerMeta):
         models.Model
             Updated model instance.
         """
-        for attr, value in payload.items():
+        for attr, value in self._parse_payload(payload).items():
             setattr(instance, attr, value)
         return await self.save(instance)