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.
Declaring a serializer
Section titled “Declaring a serializer”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.
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 })}Deserializing and validating
Section titled “Deserializing and validating”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 })Serializing
Section titled “Serializing”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 ListSerializerThe 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
Section titled “ModelSerializer”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.
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.
Relations
Section titled “Relations”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 onlytags = 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.
Nested serializers
Section titled “Nested serializers”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}Computed values
Section titled “Computed values”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.
Saving
Section titled “Saving”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 })
// updateconst 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.
Fields
Section titled “Fields”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() })Validators
Section titled “Validators”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).
JSON Schema
Section titled “JSON Schema”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 requiredThe 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.