Serializers which will be described below give to a programmer opportunities to convert complex data structures like model instances of certain ORM to the default Python datatypes. The result of this processing can be returned to a user in JSON, XML or any other formats. These serializers also provide deserializing mechanisms which can be used for parsing and validating user input data that will be used for to work with ORMs further.

These serializers largely based on ideas and concepts of Django REST Framework. In this way a lot of functionality that will be described further will coincide with this library.

At the moment aiorest-ws have support with the following ORMs:

  • Django
  • SQLAlchemy

You can find corresponding modules for each of mentioned ORMs in aiorest_ws.db.orm.* namespace.

Model serializers

The aiorest-ws library provides ModelSerializer classes which can be used for serializing (or deserializing) your model instances to a some specific format. Its can be used for processing of model instances which have taken from a database.

Defining model serializer

Let’s suppose that we have a some class which has certain functionality. For example it could be a class that storing data about a registered user:

from django.db import models

class User(models.Model):
    self.username = models.CharField(max_length=255, unique=True) = models.EmailField()
    self.logged_at = models.DateTimeField(auto_now=True)

After this we will declare a serializer class which is used for serializing and deserializing some data that converted to User objects:

from aiorest_ws.db.orm.django import serializers

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User

That’s all! We have described our simplest serializer class that giving opportunities to work with User instances. As you can see there, we have declared Meta class, that is storing a link to the User model. When we will put some data to the serializer instance (or otherwise, update data), serializer will parse specified model and extract fields that will be processed.


Serialization mechanism let us to convert complex types into Python language types. So for it is enough pass an existing object into a serializer instance and get data attribute after creating serializer. For example:

user = User.objects.create(username='nayton', email='')
serializer = UserSerializer(user)
# {'pk': 1, 'username': 'nayton', 'email': '', 'logged_at': '2016-11-29T21:13:31.039488'}

As you can see, we have converted passed object into dictionary. So it now remains to make an additional step, that allow to transmit the data through a network. For instance we can render it into JSON:

from aiorest_ws.renderers import JSONRenderer

json = JSONRenderer().render(
# b'{"pk": 1, "username": "nayton", "email": "", "logged_at": "2016-11-29T21:13:31.039488"}'


Deserializing data is very useful feature when you want to get information after users action or from 3rd party APIs and save it in a database as some model instances. For using this feature enough to use already declared serializer class:

data = {"username": "new_user", "email": "", "logged_at": "2016-11-29T21:15:31.078217"}
serializer = UserSerializer(data=data)
# True
# {'username': 'new_user', 'email': '', 'logged_at': datetime.datetime(2016, 11, 29, 21, 15, 31, 78217)}

Saving instances

In some cases if you want to return created object instances which based on the validated data then you will need to implement .create() and/or .update() methods. For example with Django ORM it can be looks like:

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User

    def create(self, validated_data):
        return User.objects.create(**validated_data)

    def update(self, instance, validated_data):
        instance.username = validated_data.get('username', instance.username) = validated_data.get('email',
        instance.logged_at = validated_data.get('logged_at', instance.logged_at)
        return instance

After then we implemented .save() method, it will return an object instance, based on the validated data:

user =

Worth noting that instances of ModelSerializer class can accept instance of a model as the an argument which is can be updated further. It leads to two different calls which can be used:

# The first case: `.save()` will create a new instance.
serializer = UserSerializer(data=data)

# The second case: `.save()` will update the existing instance.
serializer = UserSerializer(user, data=data)

Custom implementation for .create and .update() is optional. Override it only when it necessary for your use cases. You can implement one, both or neither of them for your own model serializer.

Passing additional attributes to .save()

Sometimes you can caught in the situation when necessary to pass additional data to the .save() method. These additional data can be represented like timestamps, session ids or anything else that is not part of the validated data. For solving this issue you can just include additional keyword arguments when calling .save() method. For example:['session_id'])

Each additional keyword arguments will be included in the serializer.validated_data argument when .create() or .update() are called.

Overriding .save() directly

In some cases you doesn’t want call the .create() or .update() methods, because in some use case you want to do some useful work instead of them.

The clear example for it is a feedback form which is filled by a user on your website. After a moment when you have taken the form, you are going to send a message to your administration team from a server with some text instead of saving or updating model instance. For example it might look like this:

class FeedbackMessageSerializer(serializers.ModelSerializer):

    class Meta:
        model = FeedbackMessage

    def save(self):
        email = self.validated_data['email']
        subject = self.validated_data['subject']
        message = self.validated_data['message']
        send_email(from=email, subject=subject, message=message)

Keep in mind that in this case we have a direct access to the serializer .validated_data attribute.


When deserializing data, you always should to call .is_valid() method. This method will validate passed data to a serializer instance and will return True value when the passed data are correct. Otherwise will be returned False value and all occurred errors during the validation process will be available through .errors property where each element representing the resulting error messages. For example:

data = {"username": "nayton", "email": "string", "logged_at": "2016-11-30T14:43:12.174129"}
serializer = UserSerializer(data=data)
# False
# {'username': ['User already exists.'], 'email': ['Enter a valid e-mail address.']}

Raising an exception on invalid data

Our .is_valid() method also can get an optional raise_exception flag that allow to raise a aiorest_ws.db.orm.exceptions.ValidationError exception when returned any validation errors. For example:


Field-level validation

Sometimes you might need to make additional checks for a certain field during the validation process. You can apply this checks by adding .validate_<field_name>() to your ModelSerializer subclass. Each custom field-level validation method should return the validated value or raise a ValidationError. For example:

from aiorest_ws.db.orm.django import serializers
from aiorest_ws.db.orm.exceptions import ValidationError

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User

    def validate_username(self, value):
        if value.lower() == "admin":
            raise ValidationError("Username cannot be set to 'admin'.")
        return value


If <field_name> is declared in your serializer with parameter required=False then this validation method will not apply if this field is not included.

Object-level validation

For a case when necessary to implement complex validation where are using multiple fields, you will need to implement .validate() method in your ModelSerialize subclass. This method takes a single argument which is represented as a dictionary of field values. As well this method also should return validated values or raise а ValidationError exception. For example:

from aiorest_ws.db.orm.django import serializers
from aiorest_ws.db.orm.exceptions import ValidationError

class MovieSessionSerializer(serializers.Serializer):
    name = serializers.CharField(max_length=50)
    description = serializers.CharField(max_length=255)
    start = serializers.DateTimeField()
    end = serializers.DateTimeField()

    class Meta:
        model = MovieSession

    def validate(self, data):
        Check that the start is before the end.
        if data['start'] > data['end']:
            raise ValidationError("Start timestamp cannot be greater than end.")
        return data


For each certain field can be applied list of validators via declaring them on the field instance. Those validators can be represented as functions or instances of some class. Each of them takes one argument during the validation, for example:

from aiorest_ws.db.orm.django import serializers
from aiorest_ws.db.orm.exceptions import ValidationError
from django.core.validators import MaxLengthValidator

def empty_string_validator(value):
    if not value.strip():
        raise ValidationError('Title cannot be empty.')

class PageSerializer(serializers.ModelSerializer):
    title = serializers.CharField(validators=[empty_string_validator, MaxLengthValidator(50)])

Also you can apply similar checks to the complete set of field data. For using this mechanism will be enough to specify validators attribute (as a list of used validators) in inner Meta class, like here:

from aiorest_ws.db.orm.django import serializers
from aiorest_ws.db.orm.validators import BaseUniqueFieldValidator

class UniqueTogetherValidator(BaseUniqueFieldValidator):
    Special validator class that check on uniqueness pair of fields.
    def __init__(self, queryset, fields, message=None):
        super(UniqueTogetherValidator, self).__init__(queryset, message)
        self.fields = fields

    def __call__(self, attrs):

class TrackSerializer(serializers.ModelSerializer):
    name = serializers.CharField(max_length=100)
    duration = serializers.TimeField()
    track_number = serializers.IntegerField()
    cd_name = serializers.CharField(max_length=255)

    class Meta:
        model = Track
        validators = [
                fields=('track_number', 'cd_name')

Accessing the initial data and instance

After creating an instance of a ModelSerializer subclass you can get access to following attributes which can be useful during validation or creating/updating objects: .instance and .initial_data.

The first one, .instance attribute, can be set as the first argument of aserializer subclass or with “instance” keyword. The passed instance can be initial object or queryset. If no initial object is passed then the .instance attribute will be None.

The second one, .initial_data attribute, can be set as the second argument of a serializer subclass or with “data” keyword. And when you are passing data to a serializer instance, the unmodified data will be made available as .initial_data. If the data keyword argument is not passed then the .initial_data attribute will not exist.

Partial instance updates

By default for each serializer you must specify all required fields or it will raise validation errors. For using partial updates you will need to pass partial flag with True value. For example:

# Update `user` with partial data
serializer = UserSerializer(user, data={'email': ''}, partial=True)

Dealing with nested objects

The above examples are pretty fine demonstrating how to work with a models that have a simple datatypes. But in most projects with which you will be work, will be have models this relations with which also necessary to work. And you expecting that will be able to represent more complex objects, that contains not only default datatypes.

Because each field class and ModelSerializer subclass have the same parent AbstractSerializer class, you can use these model serializers for represent relationships where one object type is nested inside another.


And here we have a difference with Django REST framework. The author of aiorest-ws library have divided the Field class onto two different classes: model serializer and its model fields. This is done in order to make it easier for programmers to understand what is happening in the process of debugging.

from aiorest_ws.db.orm.django import serializers

class CategorySerializer(serializers.ModelSerializer):
    name = serializers.CharField(max_length=255)

    class Meta:
        model = Category

class PostSerializer(serializers.Serializer):
    category = CategorySerializer()
    title = serializers.CharField(max_length=255)
    content = serializers.CharField(max_length=3000)

    class Meta:
        model = Post

In the case if a nested serializer may accept the None value, you should pass the required=False value to this nested serializer:

class PostSerializer(serializers.Serializer):
    category = CategorySerializer(required=False)  # Post can be without a category
    title = serializers.CharField(max_length=255)
    content = serializers.CharField(max_length=3000)

    class Meta:
        model = Post

For a case when a nested serializer should be represented as a list of objects, specify the many=True value to the nested serializer:

class PostSerializer(serializers.Serializer):
    category = CategorySerializer(many=True)  # A list of categories
    title = serializers.CharField(max_length=255)
    content = serializers.CharField(max_length=3000)

    class Meta:
        model = Post

Writable nested representations

When dealing with nested representations that support deserializing the data, any errors with nested objects will be nested under the field name of the nested object.

data = {'category': {'name': ''}, 'title': 'aiorest-ws docs', 'content': 'The first version of docs.'}
serializer = PostSerializer(data=data)
# False
# {'category': {'name': ['This field may not be blank.']}}

Similarly, the .validated_data property will include nested data structures.

Writing .create() methods for nested representations

For a case when necessary to support writable nested representations for a model serializer, you will need to override .create() or .update() methods that giving opportunities to work with multiple objects.

Take a look on the next example that demonstrate you how to create a Post instance with nested objects:

class PostSerializer(serializers.Serializer):
    category = CategorySerializer(many=True)
    title = serializers.CharField(max_length=255)
    content = serializers.CharField(max_length=3000)

    class Meta:
        model = Post
        fields = ('category', 'title', 'content')

    def create(self, validated_data):
        category_data = validated_data.pop('category')
        post = Post.objects.create(**validated_data)
        Category.objects.create(post=post, **category_data)
        return post

Writing .update() methods for nested representations

For a case when necessary to update an instance with nested relationships is more complex. First of all you must decide how to handle updates to relationships. What to do if the data for model relationship is None value, or perhaps not provided? We can use one of the following solutions:

  • Set the relationship to NULL in the database.
  • Delete the associated instance.
  • Ignore the data and leave the instance as it is.
  • Raise a validation error.

Take a look on the next example for an .update() method of PostSerializer class:

def update(self, instance, validated_data):
       category_data = validated_data.pop('category')
       # Unless the application properly enforces that this field is
       # always set, the follow could raise a `DoesNotExist`, which
       # would need to be handled.
       category_instance = instance.category = category_data.get('name', 'Blog')

       instance.title = validated_data.get('title', instance.title)
       instance.content = validated_data.get('content', instance.content)

       return instance

Because the behavior of nested creates and updates can be ambiguous, and may require complex dependencies between related models, ModelSerializer requires you to always write these methods explicitly. The default ModelSerializer .create() and .update() methods do not include support for writable nested representations.

Dealing with multiple objects

For each supported ORM the ModelSerializer class can also handle serializing or deserializing lists of objects.

Serializing multiple objects

For a case when necessary to serialize a queryset or list of objects instead of a single object instance, just specify the many=True flag when instantiating the model serializer. You can then specify a queryset or list of objects to be serialized.

queryset = Category.objects.all()
serializer = CategorySerializer(queryset, many=True)
# [
#     {'name': 'Documentation'},
#     {'name': 'Features'},
#     {'name': 'Change notes'}
# ]

Deserializing multiple objects

The default behavior for deserializing multiple objects is to support multiple object creation, but not support multiple object updates. For more information on how to support or customize either of these cases, see the ListSerializer documentation below.

Including extra context

In some cases you may need to provide extra context which can be used by serializer during the validating or in addition to the object being serialized. You can do this by passing a context argument when instantiating the serializer. For example:

class UserSerializer(serializers.ModelSerializer):

    class Meta:
        model = User
        fields = ('username', 'email')

    def to_representation(self, instance):
        data = super(UserSerializer, self).to_representation(instance)
        data['request_id'] = self.context['request'].request_id
        return data

serializer = UserSerializer(user, context={'request': request})
# {"username": "nayton", "email": "", "request_id": "76c3d654-b804-11e6-a794-0c4de9c846b0"}

The context dictionary can be used within any serializer field logic, such as a custom .to_representation() method, by accessing the self.context attribute.


All information that described above applied for this class and its subclasses. The ModelSerializer class define an interface that help developers in serializing and deserializing models of Django and SQLAlchemy ORMs.

What can ModelSerializer class:

  • Automatically extract and generate a set of fields based on the specified model.
  • Apply validators (and user-defined also) for the serializer and its fields.
  • Provides implementations for .create() and .update() method by default.

Example of using:

class UserSerializer(serializers.ModelSerializer):

    class Meta:
        model = User
        fields = ('pk', 'username', 'email', 'logged_at')

Inspecting a ModelSerializer

Model serializers provide a very helpful representation strings, that allow you to fully inspect a state for each serializer field. This is very useful during debugging and let you understand what kind of fields and validators are being automatically created for you.

To do so, open the you application shell, after that import the model serializer class, instantiate it, and print the object representation:

>>> from app.serializers import CarSerializer
>>> serializer = CarSerializer()
>>> print(repr(serializer))
... CarSerializer():
...    id = IntegerField(label=ID, read_only=True)
...    name = CharField(max_length=30, validators=['<UniqueValidator(queryset=django_orm_example.Car.objects)>'])
...    manufacturer = PrimaryKeyRelatedField(label=Manufacturer, queryset=django_orm_example.Manufacturer.objects)

Specifying which fields to include

If you only want a subset of the default fields to be used in a model serializer, you can do so using fields or exclude options, just as you would with a ModelForm in Django. It is strongly recommended that you explicitly set all fields that should be serialized using the fields attribute. This will make it less likely to result in unintentionally exposing data when your models change.

For example:

class UserSerializer(serializers.ModelSerializer):

    class Meta:
        model = User
        fields = ('username', 'email', 'logged_at')

You can also set the fields attribute to the special value __all__ to indicate that all fields in the model should be used.

For example:

class UserSerializer(serializers.ModelSerializer):

    class Meta:
        model = User
        fields = '__all__'

You can set the exclude attribute to a list of fields to be excluded from the serializer.

For example:

class UserSerializer(serializers.ModelSerializer):

    class Meta:
        model = User
        exclude = ('logged_at', )

In the example above, if the User model had 3 fields username, email, and logged_at, this will result in the fields username and email to be serialized.

The names in the fields and exclude attributes will normally map to model fields on the model class.

Alternatively names in the fields options can map to properties or methods which take no arguments that exist on the model class.

Specifying nested serialization

The default ModelSerializer uses primary keys for relationships, but you can also easily generate nested representations using the depth option:

class CarSerializer(serializers.ModelSerializer):

    class Meta:
        model = Account
        fields = ('id', 'name', 'manufacturer')
        depth = 1

The depth option should be set to an integer value that indicates the depth of relationships that should be traversed before reverting to a flat representation.

If you want to customize the way the serialization is done you’ll need to define the field yourself.

Specifying fields explicitly

You can add extra fields to a ModelSerializer or override the default fields by declaring fields on the class.

class CarSerializer(serializers.ModelSerializer):
    name = serializers.CharField(read_only=True)
    manufacturer = serializers.PrimaryKeyRelatedField()

    class Meta:
        model = Car

Extra fields can correspond to any property or callable on the model.

Specifying read only fields

You may wish to specify multiple fields as read-only. Instead of adding each field explicitly with the read_only=True attribute, you may use the shortcut Meta option, read_only_fields.

This option should be a list or tuple of field names, and is declared as follows:

class UserSerializer(serializers.ModelSerializer):

    class Meta:
        model = User
        fields = ('username', 'email', 'logged_at')
        read_only_fields = ('email', )

Model fields which have editable=False set, and AutoField fields will be set to read-only by default, and do not need to be added to the read_only_fields option.

Additional keyword arguments

There is also a shortcut allowing you to specify arbitrary additional keyword arguments on fields, using the extra_kwargs option. As in the case of read_only_fields, this means you do not need to explicitly declare the field on the serializer.

This option is a dictionary, mapping field names to a dictionary of keyword arguments. For example:

class CreateUserSerializer(serializers.ModelSerializer):

    class Meta:
        model = User
        fields = ('email', 'username', 'password')
        extra_kwargs = {'password': {'write_only': True}}

    def create(self, validated_data):
        user = User(
        return user

Relational fields

When serializing model instances, there are a number of different ways you might choose to represent relationships. The default representation for ModelSerializer is to use the primary keys of the related instances.

Alternative representations include serializing using hyperlinks, serializing complete nested representations, or serializing with a custom representation.

Inheritance of the ‘Meta’ class

The inner Meta class on serializers is not inherited from parent classes by default. This is the same behavior as with Django’s model. If you want the Meta class to inherit from a parent class you must do so explicitly. For example:

class UserSerializer(MyBaseSerializer):

    class Meta(MyBaseSerializer.Meta):
        model = User

Typically we would recommend not using inheritance on inner Meta classes, but instead declaring all options explicitly.

Customizing field mappings

The ModelSerializer class also exposes an API that you can override in order to alter how serializer fields are automatically determined when instantiating the serializer.

Normally if a ModelSerializer does not generate the fields you need by default then you should either add them to the class explicitly. However in some cases you may want to create a new base class that defines how the serializer fields are created for any given model.

  • .serializer_field_mapping

A mapping of Django or SQLAlchemy model classes to aiorest-ws serializer classes. You can override this mapping to alter the default serializer classes that should be used for each model class.

  • .serializer_related_field

This property should be the serializer field class, that is used for relational fields by default.

For ModelSerializer this defaults to PrimaryKeyRelatedField`.

For HyperlinkedModelSerializer this defaults to serializers.HyperlinkedRelatedField.

  • serializer_url_field

The serializer field class that should be used for any url field on the serializer.

Defaults to serializers.HyperlinkedIdentityField

  • serializer_choice_field

The serializer field class that should be used for any choice fields on the serializer.

Defaults to serializers.ChoiceField for Django ORM and serializers.EnumField for SQLAlchemy ORM.

The field_class and field_kwargs API

The following methods are called to determine the class and keyword arguments for each field that should be automatically included on the serializer. Each of these methods should return a two tuple of (field_class, field_kwargs).

  • .build_standard_field(self, field_name, model_field)

Called to generate a serializer field that maps to a standard model field.

The default implementation returns a serializer class based on the serializer_field_mapping attribute.

  • .build_relational_field(self, field_name, relation_info)

Called to generate a serializer field that maps to a relational model field.

The default implementation returns a serializer class based on the serializer_relational_field attribute.

The relation_info argument is a named tuple, that contains model_field, related_model, to_many and has_through_model properties.

  • .build_nested_field(self, field_name, relation_info, nested_depth)

Called to generate a serializer field that maps to a relational model field, when the depth option has been set.

The default implementation dynamically creates a nested serializer class based on either ModelSerializer or HyperlinkedModelSerializer.

The nested_depth will be the value of the depth option, minus one.

The relation_info argument is a named tuple, that contains model_field, related_model, to_many and has_through_model properties.

  • .build_property_field(self, field_name, model_class)

Called to generate a serializer field that maps to a property or zero-argument method on the model class.

The default implementation returns a ReadOnlyField class.

  • .build_url_field(self, field_name, model_class)

Called to generate a serializer field for the serializer’s own url field. The default implementation returns a HyperlinkedIdentityField class.

  • .build_unknown_field(self, field_name, model_class)

Called when the field name did not map to any model field or model property. The default implementation raises an error, although subclasses may customize this behavior.


The HyperlinkedModelSerializer class is similar to the ModelSerializer class except that it uses hyperlinks to represent relationships, rather than primary keys.

By default the serializer will include a url field instead of a primary key field.

The url field will be represented using a HyperlinkedIdentityField serializer field, and any relationships on the model will be represented using a HyperlinkedRelatedField serializer field.

You can explicitly include the primary key by adding it to the fields option, for example:

class UserSerializer(serializers.ModelSerializer):

    class Meta:
        model = User
        fields = ('url', 'username', 'email', 'logged_at')

Absolute and relative URLs

When instantiating a HyperlinkedModelSerializer you do not need to include the current request in the serializer context as it implemented in Django REST. Just create an serialized instance and call the .data attribute:

serializer = UserSerializer(user_queryset)

So, after getting a data from serializer instance, you will get absolute path to this object instead of primary key:


If you do want to use relative URLs, you should explicitly pass {'relative': True} to the serializer constructor as the context argument:

serializer = UserSerializer(user_object, context={'relative': True})

After that you will get a relative link to an object:


How hyperlinked views are determined

There needs to be a way of determining which views should be used for hyperlinking to model instances.

By default hyperlinks are expected to correspond to a view name that matches the style '{model_name}-detail', and looks up the instance by a pk keyword argument.

You can override a URL field view name and lookup field by using either, or both of, the view_name and lookup_field options in the extra_kwargs setting, like so:

class CarSerializer(serializers.HyperlinkedModelSerializer):

    class Meta:
        model = Account
        fields = ('car_url', 'car_model', 'factories')
        extra_kwargs = {
            'url': {'view_name': 'cars', 'lookup_field': 'car_model'}
            'factories': {'lookup_field': 'name'}

Alternatively you can set the fields on the serializer explicitly. For example:

class CarSerializer(serializers.HyperlinkedModelSerializer):
    url = serializers.HyperlinkedIdentityField(
        view_name='cars', lookup_field='car_model'
    factories = serializers.HyperlinkedRelatedField(
        view_name='factory-detail', lookup_field='name',
        many=True, read_only=True

    class Meta:
        model = Account
        fields = ('url', 'car_model', 'factories')

Tip: Properly matching together hyperlinked representations and your URL conf can sometimes be a bit fiddly. Printing the repr of a HyperlinkedModelSerializer instance is a particularly useful way to inspect exactly which view names and lookup fields the relationships are expected to map too.

Changing the URL field name

The name of the URL field defaults to url. You can override this globally, by using the URL_FIELD_NAME setting.


The ListSerializer class provides the behavior for serializing and validating multiple objects at once. You won’t typically need to use ListSerializer directly, but should instead simply pass many=True when instantiating a serializer.

When a serializer is instantiated and many=True is passed, a ListSerializer instance will be created. The serializer class then becomes a child of the parent ListSerializer.

The following argument can also be passed to a ListSerializer field or a serializer that is passed many=True:


This is True by default, but can be set to False if you want to disallow empty lists as valid input.

Customizing ListSerializer behavior

There are a few use cases when you might want to customize the ListSerializer behavior. For example:

  • You want to provide particular validation of the lists, such as checking that one element does not conflict with another element in a list.
  • You want to customize the create or update behavior of multiple objects.

For these cases you can modify the class that is used when many=True is passed, by using the list_serializer_class option on the serializer Meta class.

For example:

class CustomListSerializer(serializers.ListSerializer):

class CustomSerializer(serializers.Serializer):
    class Meta:
        list_serializer_class = CustomListSerializer

Customizing multiple create

The default implementation for multiple object creation is to simply call .create() for each item in the list. If you want to customize this behavior, you’ll need to customize the .create() method on ListSerializer class that is used when many=True is passed.

For example:

class BookListSerializer(serializers.ListSerializer):

    def create(self, validated_data):
        books = [Book(**item) for item in validated_data]
        return Book.objects.bulk_create(books)

class BookSerializer(serializers.Serializer):
    class Meta:
        list_serializer_class = BookListSerializer

Customizing multiple update

By default the ListSerializer class does not support multiple updates. This is because the behavior that should be expected for insertions and deletions is ambiguous.

To support multiple updates you’ll need to do so explicitly. When writing your multiple update code make sure to keep the following in mind:

  • How do you determine which instance should be updated for each item in the list of data?
  • How should insertions be handled? Are they invalid, or do they create new objects?
  • How should removals be handled? Do they imply object deletion, or removing a relationship? Should they be silently ignored, or are they invalid?
  • How should ordering be handled? Does changing the position of two items imply any state change or is it ignored?

You will need to add an explicit id field to the instance serializer. The default implicitly-generated id field is marked as read_only. This causes it to be removed on updates. Once you declare it explicitly, it will be available in the list serializer’s update method.

Here’s an example of how you might choose to implement multiple updates:

class BookListSerializer(serializers.ListSerializer):

    def update(self, instance, validated_data):
        # Maps for id->instance and id->data item.
        book_mapping = { book for book in instance}
        data_mapping = {item['id']: item for item in validated_data}

        # Perform creations and updates.
        ret = []
        for book_id, data in data_mapping.items():
            book = book_mapping.get(book_id, None)
            if book is None:
                ret.append(self.child.update(book, data))

        # Perform deletions.
        for book_id, book in book_mapping.items():
            if book_id not in data_mapping:

        return ret

class BookSerializer(serializers.Serializer):
    # We need to identify elements in the list using their primary key,
    # so use a writable field here, rather than the default which would be read-only.
    id = serializers.IntegerField()

    id = serializers.IntegerField(required=False)

    class Meta:
        list_serializer_class = BookListSerializer

Customizing ListSerializer initialization

When a serializer with many=True is instantiated, we need to determine which arguments and keyword arguments should be passed to the .__init__() method for both the child Serializer class, and for the parent ListSerializer class.

The default implementation is to pass all arguments to both classes, except for validators, and any custom keyword arguments, both of which are assumed to be intended for the child serializer class.

Occasionally you might need to explicitly specify how the child and parent classes should be instantiated when many=True is passed. You can do so by using the many_init class method.

def many_init(cls, *args, **kwargs):
    # Instantiate the child serializer.
    kwargs['child'] = cls()
    # Instantiate the parent list serializer.
    return CustomListSerializer(*args, **kwargs)