Serializers
Lex App automatically generates a REST API for every model. By default, all fields are exposed as-is. When you need custom validation, computed fields, or different views of the same model, you create a serializers.py file using Django REST Framework.
How It Works
- Create a
serializers.pyfile in the same folder as your models - Define one or more serializer classes
- Attach them to your model via
Model.api_serializers
The framework picks them up automatically — no registration or configuration needed.
Basic Example
Here's a serializer for an Expense model that enforces business rules — positive amounts, a cap on meal expenses, and correct handling of partial updates (PATCH requests from inline grid editing):
from rest_framework import serializers
from lex.api.views.model_entries.mixins.PermissionAwareSerializerMixin import add_permission_checks
from Input.Expense import Expense
@add_permission_checks
class ExpenseDefaultSerializer(serializers.ModelSerializer):
class Meta:
model = Expense
fields = '__all__'
def validate_amount(self, value):
"""Amounts must be positive."""
if value <= 0:
raise serializers.ValidationError("Amount must be positive.")
return value
def validate(self, attrs):
"""Enforce business rules across fields.
On partial updates (PATCH) attrs only contains the fields that
were sent in the request, so we fall back to the existing
instance for any field the user did not touch.
"""
amount = attrs.get('amount')
category = attrs.get('category')
if self.instance:
if amount is None:
amount = self.instance.amount
if category is None:
category = self.instance.category
if amount and amount > 5000 and category == 'meals':
raise serializers.ValidationError(
{'amount': "Meal expenses over €5,000 are not allowed."}
)
return attrs
Expense.api_serializers = {
'default': ExpenseDefaultSerializer,
}This example shows three important patterns:
@add_permission_checks— integrates with the permission system, enforcingpermission_read()andpermission_edit()at the API levelvalidate_<field>— field-level validation that runs automatically and shows errors inline in the gridvalidate()withself.instancefallback — cross-field validation that works correctly for both full saves (POST/PUT) and inline cell edits (PATCH, which only sends the changed field)
PATCH and cross-field validation
When a user edits a single cell in the grid, the frontend sends a PATCH request containing only that field. Invalidate(),attrswon't include the fields the user didn't touch. Always fall back toself.instancefor the "other" field — otherwise the rule silently passes.
More Validation Patterns
Here are additional patterns you can mix and match in your serializers:
Date and temporal checks
from django.utils import timezone
def validate_report_date(self, value):
"""Report date must not be in the future."""
if value > timezone.now():
raise serializers.ValidationError("Report date cannot be in the future.")
return valueConditional required fields
def validate(self, attrs):
"""Locked quarters must have a report date."""
locked = attrs.get('locked', getattr(self.instance, 'locked', False))
report_date = attrs.get('report_date', getattr(self.instance, 'report_date', None))
if locked and report_date is None:
raise serializers.ValidationError({
'report_date': "Locked quarters must have a report date."
})
return attrsComputed read-only fields
class InvestorCashflowDetailSerializer(serializers.ModelSerializer):
amount_display = serializers.SerializerMethodField()
class Meta:
model = InvestorCashflow
fields = ['id', 'investor', 'amount_eur', 'amount_display']
def get_amount_display(self, obj):
return f"€{obj.amount_eur:,.2f}" if obj.amount_eur else NoneWhen validation fails, the error message appears directly in the frontend UI — both for field-level (validate_<field>) and object-level (validate()) errors.
Computed serializer-only fields work well for display, exports, and detail views. But if a field only exists in the serializer — for example via
SerializerMethodField()— you can't use it as a row-group or pivot column in the grid. If you need grouping or pivoting, use a real model field.
Serializer validation vs.
pre_validation()
Serializer validation and pre_validation() both block invalid data before it's saved — but they run at different layers. Serializer validation runs in the API layer (when data arrives via REST), whilepre_validation()runs in the model layer (on everysave(), regardless of source). If a rule should apply no matter how the model is saved — API, management command, hook, calculation — put it inpre_validation(). If it's specific to the REST API (e.g., formatting, permission-aware checks), use a serializer.
Multiple Serializer Views
You can define multiple serializers for the same model — for example, a default view and a more detailed view:
from rest_framework import serializers
from Cashflows.InvestorCashflow import InvestorCashflow
class InvestorCashflowDefaultSerializer(serializers.ModelSerializer):
class Meta:
model = InvestorCashflow
fields = '__all__'
class InvestorCashflowDetailSerializer(serializers.ModelSerializer):
extra_info = serializers.CharField(read_only=True)
class Meta:
model = InvestorCashflow
fields = ['id', 'investor', 'vehicle', 'amount_eur',
'transaction_date', 'extra_info']
InvestorCashflow.api_serializers = {
'default': InvestorCashflowDefaultSerializer,
'detail': InvestorCashflowDetailSerializer,
}Key | When It's Used |
|---|---|
| List view and standard API calls |
| Detail view when a specific record is opened |
The
idfield is always present
When you overrideapi_serializers["default"], the framework always includes the model's primary key asidin the serialized output — even if yourMeta.fieldsomits it. Row navigation, edit URLs, and the CRUD loading overlay all depend on this field.
Renaming the framework serializer
When you override api_serializers["default"] with a custom serializer, the framework's auto-generated serializer is replaced in the map — your serializer becomes "default". For most models this is exactly what you want.
If you also need the framework-generated serializer to remain accessible (for example, so users can switch back to it in the View Preset dropdown, or if internal features like history snapshots rely on it), set DEFAULT_SERIALIZER_NAME in lex_config.py:
DEFAULT_SERIALIZER_NAME = "framework_default"With this setting, the framework-generated serializer is additionally registered under "framework_default". Both keys appear in the View Preset dropdown. Without this setting, the framework serializer is only available while no "default" override exists — once you add one, the framework serializer is no longer in the map.
Computed fields and row grouping
SerializerMethodField fields — and any other computed property with no underlying database column — are automatically marked as non-groupable. The grid will disable row group and pivot for those columns. Only real database-backed columns support server-side grouping.
History tables pick up your default override automatically
When you overrideapi_serializers["default"], the framework also registers the auto-generated serializer under the same alias on the model's history and meta-history tables. You don't need to configure anything onHistoricalInvestorCashfloworMetaHistoricalInvestorCashflow—history-endpoint and snapshot lookups stay consistent for free.
Where to Put Serializers
We recommend one serializers.py file per folder, containing all serializers for the models in that folder:
Input/
├── __init__.py
├── Team.py
├── Employee.py
├── Expense.py
└── serializers.py ← serializers for all Input models
Reports/
├── __init__.py
├── BudgetSummary.py
└── serializers.py ← serializers for all Report modelsYou could create a separate file per serializer (e.g., ExpenseSerializer.py), but in practice a single file per folder is easier to navigate — you can see all validation rules and field configurations for related models in one place, and the imports stay clean since the models are all in the same folder.
You don't have to create serializers. Without them, Lex App generates a default serializer that exposes all fields. Custom serializers are for when you need validation, computed fields, or restricted views.
For more on the REST API and Django REST Framework, see the official DRF documentation.
Was this helpful?
Your feedback shapes what we write next.
