🔄 Serialization with Marshmallow

What Is Serialization?

Serialization is converting an in-memory object (like a SQLAlchemy row) into a format you can send over the network — almost always JSON. Deserialization is the reverse: taking incoming JSON and turning it back into validated Python data your app can trust.

💡 Analogy: Marshmallow is a bilingual translator with a strict grammar checker. When your app "speaks" to a client, it translates Python into JSON. When a client speaks back, it not only translates but refuses messages that break the grammar — the wrong type, a missing required field, an out-of-range value.

Why Marshmallow?

Flask-RESTful's marshaling handles output, and reqparse handles input — but they're two separate systems with limited validation. Marshmallow unifies both directions in one reusable schema and adds much richer validation.

Your First Schema

Install the libraries:

pip install marshmallow flask-marshmallow marshmallow-sqlalchemy

A schema is a class describing the shape of your data. Each attribute is a typed field:

from marshmallow import Schema, fields, ValidationError


class UserSchema(Schema):
    id = fields.Integer(dump_only=True)      # only serialized, never accepted as input
    username = fields.String(required=True)
    email = fields.Email(required=True)      # validates email format automatically
    created_at = fields.DateTime(dump_only=True)
    bio = fields.String()


user_schema = UserSchema()             # one object
users_schema = UserSchema(many=True)   # a collection

Serializing (dump)

user = {"id": 1, "username": "johndoe", "email": "john@example.com",
        "created_at": "2024-01-15T12:30:45", "bio": "Developer"}

result = user_schema.dump(user)
# result is a plain dict, ready for jsonify()

Deserializing (load) with validation

try:
    data = user_schema.load({"username": "jane", "email": "jane@example.com"})
    # data is a validated dict; id and created_at were ignored (dump_only)
except ValidationError as err:
    print(err.messages)   # e.g. {"email": ["Not a valid email address."]}

Fields & Validation

Marshmallow ships a rich set of field types, each mapping a JSON value to a Python type.

Built-in validators

from marshmallow import Schema, fields
from marshmallow.validate import Length, Range, OneOf, Regexp


class SignupSchema(Schema):
    username = fields.String(required=True, validate=Length(min=3, max=50))
    age = fields.Integer(validate=Range(min=18, max=120))
    role = fields.String(validate=OneOf(["user", "admin", "editor"]))
    phone = fields.String(validate=Regexp(r"^\d{3}-\d{3}-\d{4}$"))

Custom validators

A validator is any callable that raises ValidationError on bad input:

from marshmallow import ValidationError

RESERVED = {"admin", "root", "superuser"}

def not_reserved(value: str) -> None:
    if value.lower() in RESERVED:
        raise ValidationError("This username is reserved.")


class UserSchema(Schema):
    username = fields.String(required=True, validate=not_reserved)

Nested Schemas

Real data has structure — a user has an address, a post has comments. fields.Nested composes schemas to represent those relationships.

A nested object

class AddressSchema(Schema):
    street = fields.String(required=True)
    city = fields.String(required=True)
    zip_code = fields.String(required=True)


class UserSchema(Schema):
    id = fields.Integer(dump_only=True)
    username = fields.String(required=True)
    address = fields.Nested(AddressSchema)   # single nested object

A nested collection

class CommentSchema(Schema):
    id = fields.Integer(dump_only=True)
    content = fields.String(required=True)


class PostSchema(Schema):
    id = fields.Integer(dump_only=True)
    title = fields.String(required=True)
    comments = fields.Nested(CommentSchema, many=True)   # a list of comments

{
  "id": 123,
  "title": "My First Post",
  "comments": [
    { "id": 1, "content": "Great post!" },
    { "id": 2, "content": "Thanks for sharing." }
  ]
}

Trimming nested fields

Use only and exclude to control exactly which nested fields appear — essential for avoiding over-fetching and infinite loops in circular relationships:

# Include only id and username of the author
author = fields.Nested(UserSchema, only=("id", "username"))

# Exclude sensitive or heavy fields
author = fields.Nested(UserSchema, exclude=("email", "bio"))

# Self-reference for tree structures (categories with children)
children = fields.Nested("self", many=True, exclude=("parent_id",))

Method Fields & Hooks

Sometimes a field is computed, or data needs massaging before or after processing. Marshmallow provides method fields and lifecycle hooks for this.

Computed fields

class UserSchema(Schema):
    first_name = fields.String(required=True)
    last_name = fields.String(required=True)

    # Calls get_full_name(self, obj) during serialization
    full_name = fields.Method("get_full_name")

    def get_full_name(self, obj):
        return f"{obj['first_name']} {obj['last_name']}"

Lifecycle hooks

from marshmallow import Schema, fields, pre_load, post_load, post_dump


class UserSchema(Schema):
    username = fields.String(required=True)
    email = fields.Email(required=True)
    password = fields.String(load_only=True, required=True)

    @pre_load
    def normalize_email(self, data, **kwargs):
        # Runs before validation on incoming data
        if data.get("email"):
            data["email"] = data["email"].strip().lower()
        return data

    @post_load
    def make_user(self, data, **kwargs):
        # Runs after successful validation — turn the dict into an object
        return User(**data)

    @post_dump
    def drop_nulls(self, data, **kwargs):
        # Runs after serialization — remove keys whose value is None
        return {k: v for k, v in data.items() if v is not None}

SQLAlchemyAutoSchema

Writing a schema that mirrors a model field-for-field is tedious and drifts out of sync. marshmallow-sqlalchemy generates the schema from the model, so they can never disagree.

from datetime import datetime, timezone
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_marshmallow import Marshmallow
from marshmallow_sqlalchemy import SQLAlchemyAutoSchema, auto_field
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


class Base(DeclarativeBase):
    pass


db = SQLAlchemy(model_class=Base)
ma = Marshmallow()


class User(db.Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    username: Mapped[str] = mapped_column(db.String(80), unique=True)
    email: Mapped[str] = mapped_column(db.String(120), unique=True)
    password: Mapped[str] = mapped_column(db.String(256))
    created_at: Mapped[datetime] = mapped_column(
        default=lambda: datetime.now(timezone.utc)
    )


class UserSchema(SQLAlchemyAutoSchema):
    class Meta:
        model = User
        load_instance = True     # load() returns a User instance, not a dict
        exclude = ("password",)  # never serialize the password
        sqla_session = db.session


user_schema = UserSchema()
users_schema = UserSchema(many=True)

The schema automatically infers a field for every column, choosing the right Marshmallow type. You only write code for the exceptions — excluding password, adding validation, or overriding a relationship field with ma.Nested(...).

Using it in a Flask route

from flask import request, jsonify
from marshmallow import ValidationError

app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
db.init_app(app)
ma.init_app(app)


@app.get("/users/<int:user_id>")
def get_user(user_id):
    user = db.get_or_404(User, user_id)
    return jsonify(user_schema.dump(user))


@app.post("/users")
def create_user():
    try:
        user = user_schema.load(request.get_json())  # validated User instance
    except ValidationError as err:
        return jsonify({"errors": err.messages}), 400
    db.session.add(user)
    db.session.commit()
    return jsonify(user_schema.dump(user)), 201


@app.put("/users/<int:user_id>")
def update_user(user_id):
    user = db.get_or_404(User, user_id)
    try:
        # partial=True allows updating only some fields
        user_schema.load(request.get_json(), instance=user, partial=True)
    except ValidationError as err:
        return jsonify({"errors": err.messages}), 400
    db.session.commit()
    return jsonify(user_schema.dump(user))

Validation Error Handling

When load() fails, it raises ValidationError whose .messages is a dict mapping each bad field to its problems. Register one error handler and every route gets consistent 400s for free.

from marshmallow import ValidationError
from flask import jsonify


@app.errorhandler(ValidationError)
def handle_validation_error(err):
    return jsonify({"error": "Validation failed", "messages": err.messages}), 400

{
  "error": "Validation failed",
  "messages": {
    "email": ["Not a valid email address."],
    "username": ["Missing data for required field."],
    "age": ["Must be greater than or equal to 18."]
  }
}

Field- and schema-level validation

from marshmallow import Schema, fields, validates, validates_schema, ValidationError
from marshmallow.validate import Length


class SignupSchema(Schema):
    username = fields.String(required=True, validate=Length(min=3))
    password = fields.String(required=True, load_only=True)
    password_confirm = fields.String(required=True, load_only=True)

    @validates("password")
    def check_strength(self, value, **kwargs):
        if len(value) < 8 or not any(c.isdigit() for c in value):
            raise ValidationError("Password needs 8+ characters and a digit.")

    @validates_schema
    def passwords_match(self, data, **kwargs):
        if data.get("password") != data.get("password_confirm"):
            raise ValidationError("Passwords must match.", "password_confirm")

Use @validates("field") when a rule concerns one field, and @validates_schema when a rule spans several fields (like confirming two passwords match, or checking an end date is after a start date).

Hands-on Exercise

from flask import request, jsonify
from marshmallow import Schema, fields, validates_schema, ValidationError
from marshmallow.validate import Length, Range, OneOf, Regexp


class ProductSchema(Schema):
    id = fields.Integer(dump_only=True)
    name = fields.String(required=True, validate=Length(min=2, max=100))
    price = fields.Float(required=True,
                         validate=Range(min=0, min_inclusive=False))
    currency = fields.String(required=True,
                            validate=OneOf(["USD", "EUR", "GBP"]))
    sku = fields.String(required=True,
                       validate=Regexp(r"^[A-Z]{3}-\d{4}$"))

    @validates_schema
    def usd_price_cap(self, data, **kwargs):
        if data.get("currency") == "USD" and data.get("price", 0) > 10000:
            raise ValidationError("USD price cannot exceed 10000.", "price")


product_schema = ProductSchema()


@app.post("/products")
def create_product():
    try:
        data = product_schema.load(request.get_json())
    except ValidationError as err:
        return jsonify({"errors": err.messages}), 400
    # (persist data here in a real app)
    return jsonify(product_schema.dump({"id": 1, **data})), 201

Best Practices

Summary & Quiz

📚 Further Reading

• Marshmallow Documentation
• Flask-Marshmallow Documentation
• Marshmallow-SQLAlchemy Documentation
• Flask-Smorest — Marshmallow + OpenAPI

🚀 What's Next?

You've now covered the full Flask API toolkit — routing, resources, structure, and serialization. It's time to put it all together in the Weekend Project, where you'll build a complete, database-backed Flask API from scratch and validate every request with Marshmallow.