Serializer Fields - Django REST Framework

Serializer fields handle converting between primitive values and internal datatypes. They also deal with validating input values, as well as retrieving and setting the values from their parent objects.

Core Arguments

All field types accept the following arguments:

read_only

bool

default:"False"

Field is used for serialization but not deserialization.

write_only

bool

default:"False"

Field is used for deserialization but not serialization.

required

bool

default:"True"

Field must be present in input data during deserialization.

default

any

Default value if no input is supplied. Can be a value or callable.

allow_null

bool

default:"False"

Accept None as a valid value.

source

str

Attribute name to use for populating the field. Use '*' for the entire object.

validators

list

List of validator functions to apply to the field input.

error_messages

dict

Dictionary of error codes to error messages.

label

str

Short text string for HTML form fields.

help_text

str

Description text for HTML form fields.

initial

any

Value for pre-populating HTML form fields.

style

dict

Key-value pairs to control renderer display.

Boolean Fields

BooleanField

A boolean representation.

BooleanField()

Valid inputs: True, False, 't', 'f', 'true', 'false', '1', '0', 1, 0, 'yes', 'no', 'on', 'off' Output: True or False Example:

is_active = serializers.BooleanField()

String Fields

CharField

A text representation.

CharField(
    max_length=None,
    min_length=None,
    allow_blank=False,
    trim_whitespace=True
)

max_length

int

Maximum number of characters.

min_length

int

Minimum number of characters.

allow_blank

bool

default:"False"

Allow empty string as valid value.

trim_whitespace

bool

default:"True"

Trim leading and trailing whitespace.

Example:

title = serializers.CharField(max_length=100)
content = serializers.CharField(max_length=200, allow_blank=True)

EmailField

A text representation that validates email addresses.

EmailField(max_length=None, min_length=None, allow_blank=False)

Example:

email = serializers.EmailField()

RegexField

A text representation that validates against a regular expression.

RegexField(regex, max_length=None, min_length=None, allow_blank=False)

regex

str | Pattern

required

Regular expression string or compiled pattern object.

Example:

phone = serializers.RegexField(regex=r'^\+?1?\d{9,15}$')

SlugField

Validates against the pattern [a-zA-Z0-9_-]+.

SlugField(max_length=50, min_length=None, allow_blank=False, allow_unicode=False)

allow_unicode

bool

default:"False"

Allow Unicode letters in addition to ASCII.

Example:

slug = serializers.SlugField(max_length=100)

URLField

Validates fully qualified URLs.

URLField(max_length=200, min_length=None, allow_blank=False)

Example:

website = serializers.URLField()

UUIDField

Ensures input is a valid UUID string.

UUIDField(format='hex_verbose')

format

str

default:"'hex_verbose'"

UUID format: 'hex_verbose', 'hex', 'int', or 'urn'.

Example:

id = serializers.UUIDField(format='hex')

FilePathField

Choices limited to filenames in a directory.

FilePathField(
    path,
    match=None,
    recursive=False,
    allow_files=True,
    allow_folders=False
)

path

str

required

Absolute filesystem path to directory.

match

str

Regular expression to filter filenames.

recursive

bool

default:"False"

Include all subdirectories.

allow_files

bool

default:"True"

Include files in choices.

allow_folders

bool

default:"False"

Include folders in choices.

IPAddressField

Validates IPv4 or IPv6 addresses.

IPAddressField(protocol='both', unpack_ipv4=False)

protocol

str

default:"'both'"

Accepted values: 'both', 'IPv4', or 'IPv6'.

unpack_ipv4

bool

default:"False"

Unpack IPv4 mapped addresses like ::ffff:192.0.2.1.

Numeric Fields

IntegerField

An integer representation.

IntegerField(max_value=None, min_value=None)

max_value

int

Maximum value allowed.

min_value

int

Minimum value allowed.

Example:

age = serializers.IntegerField(min_value=0, max_value=150)

BigIntegerField

A biginteger representation.

BigIntegerField(max_value=None, min_value=None, coerce_to_string=None)

coerce_to_string

bool

Return string values. Defaults to COERCE_BIGINT_TO_STRING setting.

Example:

large_number = serializers.BigIntegerField()

FloatField

A floating point representation.

FloatField(max_value=None, min_value=None)

Example:

price = serializers.FloatField(min_value=0.0)

DecimalField

A decimal representation.

DecimalField(
    max_digits,
    decimal_places,
    coerce_to_string=None,
    max_value=None,
    min_value=None,
    localize=False,
    rounding=None,
    normalize_output=False
)

max_digits

int

required

Maximum number of digits allowed.

decimal_places

int

required

Number of decimal places to store.

coerce_to_string

bool

Return string values. Defaults to COERCE_DECIMAL_TO_STRING setting.

max_value

int | Decimal

Maximum value allowed.

min_value

int | Decimal

Minimum value allowed.

localize

bool

default:"False"

Enable localization of input and output.

rounding

str

Decimal rounding mode.

normalize_output

bool

default:"False"

Strip trailing zeros from output.

Example:

price = serializers.DecimalField(max_digits=5, decimal_places=2)

Date and Time Fields

DateTimeField

A date and time representation.

DateTimeField(
    format=empty,
    input_formats=None,
    default_timezone=None
)

format

str

Output format: strftime string or 'iso-8601'. Defaults to DATETIME_FORMAT setting.

input_formats

list

List of input format strings. Defaults to DATETIME_INPUT_FORMATS setting.

default_timezone

tzinfo

Timezone for naive datetimes. Defaults to current timezone if USE_TZ is enabled.

Example:

created = serializers.DateTimeField()
timestamp = serializers.DateTimeField(format='%Y-%m-%d %H:%M:%S')

DateField

A date representation.

DateField(format=empty, input_formats=None)

Example:

birthday = serializers.DateField()

TimeField

A time representation.

TimeField(format=empty, input_formats=None)

Example:

meeting_time = serializers.TimeField()

DurationField

A duration representation.

DurationField(format=empty, max_value=None, min_value=None)

format

str

Output format: 'iso-8601' or 'django'. Defaults to DURATION_FORMAT setting.

Example:

video_length = serializers.DurationField()

Choice Fields

ChoiceField

Accepts a value from a limited set of choices.

ChoiceField(choices, allow_blank=False, html_cutoff=None, html_cutoff_text=None)

choices

list

required

List of valid values or (key, display_name) tuples.

allow_blank

bool

default:"False"

Allow empty string as valid value.

html_cutoff

int

Maximum choices displayed in HTML select.

html_cutoff_text

str

Text indicator for cutoff choices.

Example:

status = serializers.ChoiceField(choices=['draft', 'published', 'archived'])

MultipleChoiceField

Accepts a list of values from a set of choices.

MultipleChoiceField(choices, allow_blank=False, html_cutoff=None, html_cutoff_text=None)

Example:

tags = serializers.MultipleChoiceField(choices=['python', 'django', 'rest'])

File Upload Fields

FileField

A file representation.

FileField(max_length=None, allow_empty_file=False, use_url=True)

max_length

int

Maximum length for filename.

allow_empty_file

bool

default:"False"

Allow empty files.

use_url

bool

default:"True"

Use URL strings in output representation.

Example:

document = serializers.FileField()

ImageField

An image representation with validation.

ImageField(max_length=None, allow_empty_file=False, use_url=True)

Requires Pillow library. Example:

profile_picture = serializers.ImageField()

Composite Fields

ListField

Validates a list of objects.

ListField(child=None, allow_empty=True, min_length=None, max_length=None)

child

Field

Field instance for validating list items.

allow_empty

bool

default:"True"

Allow empty lists.

min_length

int

Minimum number of elements.

max_length

int

Maximum number of elements.

Example:

scores = serializers.ListField(
    child=serializers.IntegerField(min_value=0, max_value=100)
)

DictField

Validates a dictionary of objects.

DictField(child=None, allow_empty=True)

child

Field

Field instance for validating dictionary values.

Example:

metadata = serializers.DictField(child=serializers.CharField())

HStoreField

PostgreSQL HStore field.

HStoreField(child=None, allow_empty=True)

Example:

attributes = serializers.HStoreField()

JSONField

Validates JSON primitives.

JSONField(binary=False, encoder=None)

binary

bool

default:"False"

Output JSON-encoded string instead of primitive data.

encoder

JSONEncoder

Custom JSON encoder class.

Example:

config = serializers.JSONField()

Miscellaneous Fields

ReadOnlyField

Returns field value without modification.

ReadOnlyField()

Example:

owner_name = serializers.ReadOnlyField(source='owner.username')

HiddenField

Takes value from default or callable, not user input.

HiddenField(default=None)

Example:

modified = serializers.HiddenField(default=timezone.now)

ModelField

Delegates to an arbitrary Django model field.

ModelField(model_field=None)

Example:

field = serializers.ModelField(
    model_field=MyModel()._meta.get_field('custom_field')
)

SerializerMethodField

Read-only field that calls a method on the serializer.

SerializerMethodField(method_name=None)

method_name

str

Method name to call. Defaults to get_<field_name>.

Example:

class UserSerializer(serializers.ModelSerializer):
    days_since_joined = serializers.SerializerMethodField()

    def get_days_since_joined(self, obj):
        return (now() - obj.date_joined).days

Views & ViewSets

Serializers

Requests & Responses

Authentication & Permissions

Parsers & Renderers

Additional Components

​Core Arguments

​Boolean Fields

​BooleanField

​String Fields

​CharField

​EmailField

​RegexField

​SlugField

​URLField

​UUIDField

​FilePathField

​IPAddressField

​Numeric Fields

​IntegerField

​BigIntegerField

​FloatField

​DecimalField

​Date and Time Fields

​DateTimeField

​DateField

​TimeField

​DurationField

​Choice Fields

​ChoiceField

​MultipleChoiceField

​File Upload Fields

​FileField

​ImageField

​Composite Fields

​ListField

​DictField

​HStoreField

​JSONField

​Miscellaneous Fields

​ReadOnlyField

​HiddenField

​ModelField

​SerializerMethodField

Build docs developers (and LLMs) love

Core Arguments

Boolean Fields

BooleanField

String Fields

CharField

EmailField

RegexField

SlugField

URLField

UUIDField

FilePathField

IPAddressField

Numeric Fields

IntegerField

BigIntegerField

FloatField

DecimalField

Date and Time Fields

DateTimeField

DateField

TimeField

DurationField

Choice Fields

ChoiceField

MultipleChoiceField

File Upload Fields

FileField

ImageField

Composite Fields

ListField

DictField

HStoreField

JSONField

Miscellaneous Fields

ReadOnlyField

HiddenField

ModelField

SerializerMethodField