Skip to content

Serializers

A serializer does two jobs. Going in, it turns untrusted request data into validated values you can save. Going out, it turns model instances into plain JSON-ready objects. It is the API equivalent of a Django form.

Fields are declared as instance properties. Field classes come from @ghuri/rest. They share names with the ORM’s field classes (CharField, IntegerField …), so a serializers.ts file should import fields only from @ghuri/rest and import models as classes.

src/blog/serializers.ts
import { Serializer, CharField, EmailField, DateTimeField } from '@ghuri/rest'
export class ContactSerializer extends Serializer {
name = new CharField({ maxLength: 100 })
email = new EmailField()
message = new CharField({ style: { widget: 'textarea' } })
sentAt = new DateTimeField({ readOnly: true })
}

Pass the incoming data as data, then validate. isValid() is async because some validators (for example UniqueValidator) query the database.

const serializer = new ContactSerializer({ data: await c.req.json() })
if (await serializer.isValid()) {
serializer.validatedData // { name: 'Ada', email: 'ada@example.com', message: '…' }
} else {
serializer.errors // { email: ['Enter a valid email address.'] }
}

In views you usually let the error propagate. With raiseException: true a failed validation throws a REST ValidationError, which the exception handler turns into a 400 with the errors as the body:

await serializer.isValid({ raiseException: true })

Pass an instance (or a list or QuerySet with many: true) and await the output:

const post = await Post.objects.get({ slug: 'hello' })
const data = await new PostSerializer(post).getData() // same as new PostSerializer({ instance: post })
// { id: 1, title: 'Hello', slug: 'hello', author: 'rifat', ... }
const posts = Post.objects.filter({ published: true })
const list = await new PostSerializer({ instance: posts, many: true }).getData()
// typed alternative: PostSerializer.many({ instance: posts }) returns a ListSerializer

The constructor takes one options object: instance, data, partial, context (generic views pass { request, view, format }), many, plus any field option (readOnly, required …) for when the serializer is nested as a field.

ModelSerializer builds its fields from the model’s _meta: field types, maxLength, choices, null/blank (which become allowNull/required), unique constraints and relations. You list the fields you want in static Meta.

src/blog/serializers.ts
import { ModelSerializer, CharField, ValidationError } from '@ghuri/rest'
import { Post } from './models'
export class PostSerializer extends ModelSerializer<Post> {
static Meta = {
model: Post,
fields: ['id', 'title', 'slug', 'body', 'published', 'author', 'authorName', 'tags', 'createdAt'],
readOnlyFields: ['author', 'createdAt'],
extraKwargs: { slug: { required: false } },
}
authorName = new CharField({ source: 'author.username', readOnly: true })
validateTitle(value: string) {
if (value.toLowerCase().includes('spam')) throw new ValidationError('No spam, please.')
return value
}
validate(attrs: Record<string, unknown>) {
if (attrs.published && !attrs.body) {
throw new ValidationError({ body: ['A published post needs a body.'] })
}
return attrs
}
}

Meta options:

Option Meaning
model The model class
fields Field names to include, or '__all__'
exclude Field names to leave out (instead of fields)
readOnlyFields Included in output, ignored on input
extraKwargs Per-field option overrides, e.g. { password: { writeOnly: true } }
depth Render relations as nested objects this many levels deep (read only)
validators Serializer-level validators such as UniqueTogetherValidator (replaces the generated ones)
fullClean Also run the model’s fullClean() (field validators, clean(), uniqueness) before saving; its errors become a 400
listSerializerClass The ListSerializer subclass used for many: true

A field declared on the class always wins over the generated one with the same name. Unlike DRF, a declared field missing from Meta.fields is appended instead of raising. Reverse relations (comments) may be listed in fields and are read only. HyperlinkedModelSerializer renders relations as URLs and adds a url field, resolved through the <model>-detail URL names that routers create.

By default a ForeignKey renders as its primary key (PrimaryKeyRelatedField) and a ManyToManyField as an array of primary keys. On input the serializer looks those keys up and reports Invalid pk "42" - object does not exist. for missing ones.

Other relation fields:

author = new StringRelatedField() // uses toString(), read only
tags = new SlugRelatedField({ slugField: 'name', many: true, queryset: Tag.objects.all() })
post = new PrimaryKeyRelatedField({ queryset: Post.objects.filter({ published: true }) })

Use selectRelated and prefetchRelated in the view’s queryset so that rendering a list does not issue one query per row.

Use another serializer as a field to embed related objects:

export class CommentSerializer extends ModelSerializer<Comment> {
static Meta = { model: Comment, fields: ['id', 'author', 'body', 'createdAt'] }
author = new StringRelatedField()
}
export class PostDetailSerializer extends ModelSerializer<Post> {
static Meta = { model: Post, fields: ['id', 'title', 'body', 'comments'] }
comments = new CommentSerializer({ many: true, readOnly: true })
}

Nested serializers are read only by default, as in DRF. To accept nested input, override create() and update() and write the related objects yourself:

async create(validatedData: Record<string, any>) {
const { tags = [], ...rest } = validatedData
const post = await Post.objects.create(rest)
await post.tags.set(tags)
return post
}

SerializerMethodField calls get<FieldName> on the serializer. The method may be async.

commentCount = new SerializerMethodField()
async getCommentCount(post: Post) {
return post.comments.count()
}

If you need the count on every row of a list, annotate the queryset instead (Post.objects.annotate({ commentCount: Count('comments') })) and declare commentCount = new IntegerField({ readOnly: true }). One query beats N.

After validation, save() calls create() or update() depending on whether the serializer was constructed with an instance. Keyword data passed to save() is merged into validatedData, which is how views attach values that do not come from the client:

const serializer = new PostSerializer({ data: this.request.data })
await serializer.isValid({ raiseException: true })
const post = await serializer.save({ author: this.request.user })
// update
const edit = new PostSerializer({ instance: post, data: { title: 'New title' }, partial: true })
await edit.isValid({ raiseException: true })
await edit.save()

ModelSerializer.create() and update() set many-to-many fields after the instance is saved, so tags works without extra code. On a plain Serializer you write create() and update() yourself; save() throws if the one it needs is missing.

All fields accept readOnly, writeOnly, required, default, allowNull, source, validators, errorMessages, label and helpText.

Field Notes
CharField maxLength, minLength, allowBlank, trimWhitespace (default true)
EmailField, URLField, UUIDField, SlugField, IPAddressField Validated strings
RegexField new RegexField(/^[A-Z]{3}$/, opts?): the pattern (a RegExp or string) is the first argument
IntegerField, FloatField minValue, maxValue
DecimalField maxDigits, decimalPlaces; values are strings, as in the ORM
BooleanField, NullBooleanField Accepts true/false, "true", "1", "on" …
DateTimeField, DateField, TimeField ISO 8601 in and out
DurationField Milliseconds (the ORM’s representation); output uses DRF’s [DD ]HH:MM:SS[.uuuuuu]
ChoiceField, MultipleChoiceField new ChoiceField(choices, opts?): choices is the first argument ([value, label][], a list of values, a { value: label } object or a Map), not an option; allowBlank, and allowEmpty on MultipleChoiceField
ListField, DictField child field for elements
JSONField Any JSON value
FileField, ImageField Multipart uploads; see File storage
SerializerMethodField Read only, calls get<Name>()
PrimaryKeyRelatedField, SlugRelatedField, StringRelatedField Relations
HyperlinkedRelatedField, HyperlinkedIdentityField Relations as URLs, via reverse()
HiddenField Not in input or output; value from default, e.g. CurrentUserDefault
ReadOnlyField Renders the attribute as is

default may be a value, a function, or new CurrentUserDefault(). source takes a dotted path ('author.username', awaiting the relation) or '*' for the whole object.

HiddenField with CurrentUserDefault is the idiomatic way to set an owner without trusting the client:

author = new HiddenField({ default: new CurrentUserDefault() })

Field-level validation runs in this order: the field’s own checks, its validators, then the serializer’s validate<Field>() method. Object-level validation (Meta.validators, then validate()) runs once every field is valid. Validators and hooks may be async and may throw either the REST ValidationError or @ghuri/core’s, so the ORM’s validators work unchanged.

import { UniqueValidator, UniqueTogetherValidator } from '@ghuri/rest'
slug = new CharField({ validators: [new UniqueValidator({ queryset: Post.objects.all() })] })
static Meta = {
model: Comment,
fields: ['post', 'author', 'body'],
validators: [new UniqueTogetherValidator({ queryset: Comment.objects.all(), fields: ['post', 'author'] })],
}

ModelSerializer adds UniqueValidator automatically for model fields with unique: true, and UniqueTogetherValidator for the model’s uniqueTogether. Errors raised from validate() without a field key go under nonFieldErrors (configurable with NON_FIELD_ERRORS_KEY).

Every serializer can describe itself as JSON Schema (2020-12):

PostSerializer.jsonSchema() // output schema
// { type: 'object', properties: { title: { type: 'string', maxLength: 200 }, ... }, required: [...] }
new PostSerializer().jsonSchema({ mode: 'input', partial: true }) // writable fields only, nothing required

The OpenAPI generator and the agents package both use this to describe inputs and outputs, so a field’s helpText ends up in your API docs and in the tool descriptions an LLM sees.