marshmallow — Object Serialization and Validation for Python

Introduction

marshmallow provides a declarative way to define schemas that validate input data, deserialize it into application objects, and serialize objects back into simple types suitable for JSON or database storage. It is framework-agnostic and works with Flask, Django, and any Python application.

What marshmallow Does

• Validates incoming data against a defined schema with detailed error messages
• Deserializes dictionaries into application objects or validated dicts
• Serializes complex objects into JSON-compatible primitives
• Supports nested schemas for complex hierarchical data structures
• Provides hooks for pre/post processing during load and dump operations

Architecture Overview

A marshmallow Schema is a class with Field instances as class attributes. When load() is called, each field validates and transforms its corresponding input key. The schema collects errors into a structured dictionary and either raises a ValidationError or returns cleaned data. dump() reverses the process for serialization.

Self-Hosting & Configuration

• Install via pip; pure Python with zero compiled dependencies
• Define schemas as classes inheriting from marshmallow.Schema
• Use Meta inner class to configure field ordering, strict mode, and unknown field handling
• Combine with Flask-Marshmallow or Django REST Marshmallow for web framework integration
• Use marshmallow-dataclass to generate schemas from dataclass definitions

Key Features

• Declarative field types including Str, Int, Float, DateTime, Nested, List, and custom types
• Validation via built-in validators or custom functions attached to fields
• Two-way transformation: load (deserialize) and dump (serialize) with different field configurations
• Schema inheritance and field overriding for DRY definitions
• Pluggable and composable with pre_load, post_load, pre_dump, post_dump hooks

Comparison with Similar Tools

• Pydantic — uses type annotations and is faster; marshmallow uses explicit field declarations and has richer serialization hooks
• attrs + cattrs — attrs for classes, cattrs for un/structuring; less focus on validation
• Cerberus — dict-based validation without ORM-style serialization
• Django REST Framework Serializers — similar concept but tightly coupled to Django

FAQ

Q: How does marshmallow compare to Pydantic? A: Pydantic validates via type annotations and is faster at runtime. marshmallow offers more granular control over serialization/deserialization logic and richer hook systems. Choose Pydantic for new projects prioritizing speed; marshmallow for complex transformation pipelines.

Q: Can marshmallow validate nested objects? A: Yes. Use fields.Nested(OtherSchema) to validate and deserialize nested structures recursively.

Q: Does marshmallow support partial loading? A: Yes. Pass partial=True to load() to skip required field validation, useful for PATCH endpoints.

Q: How do I handle unknown fields? A: Set unknown = EXCLUDE, INCLUDE, or RAISE in the schema's Meta class to control behavior for fields not defined in the schema.

Sources

• https://github.com/marshmallow-code/marshmallow
• https://marshmallow.readthedocs.io