Skip to content
Back to top
View this page

# marshmallow

Object serialization and deserialization, lightweight and fluffy.

Release v3.26.1. (Changelog)

marshmallow is an ORM/ODM/framework-agnostic library for converting complex datatypes, such as objects, to and from native Python datatypes.

    from datetime import date
    from pprint import pprint

    from marshmallow import Schema, fields

    class ArtistSchema(Schema):
        name = fields.Str()

    class AlbumSchema(Schema):
        title = fields.Str()
        release_date = fields.Date()
        artist = fields.Nested(ArtistSchema())

    bowie = dict(name="David Bowie")
    album = dict(artist=bowie, title="Hunky Dory", release_date=date(1971, 12, 17))

    schema = AlbumSchema()
    result = schema.dump(album)
    pprint(result, indent=2)
    # { 'artist': {'name': 'David Bowie'},
    #   'release_date': '1971-12-17',
    #   'title': 'Hunky Dory'}

In short, marshmallow schemas can be used to:

- Validate input data.

- Deserialize input data to app-level objects.

- Serialize app-level objects to primitive Python types. The serialized objects can then be rendered to standard formats such as JSON for use in an HTTP API.

## Get it now

    $ pip install -U marshmallow

Ready to get started? Go on to the Quickstart or check out some examples.

## Upgrading from an older version?

See the Upgrading to newer releases page for notes on getting your code up-to-date with the latest version.

## Why another library?

See this document to learn about what makes marshmallow unique.

## Sponsors

marshmallow is sponsored by Route4Me.

Support this project by becoming a sponsor (or ask your company to support this project by becoming a sponsor). Your logo will be displayed here with a link to your website. [Become a sponsor]

## Usage guide

Usage guide

- Installation
  - Installing/upgrading from the PyPI
  - Get the bleeding edge version
- Quickstart
  - Declaring schemas
  - Serializing objects (“dumping”)
  - Filtering output
  - Deserializing objects (“loading”)
  - Handling collections of objects
  - Validation
  - Required fields
  - Partial loading
  - Specifying defaults
  - Handling unknown fields
  - Validation without deserialization
  - “Read-only” and “write-only” fields
  - Specifying serialization/deserialization keys
  - Implicit field creation
  - Next steps
- Nesting schemas
  - Specifying which fields to nest
  - Partial loading
  - Two-way nesting
  - Nesting a schema within itself
  - Next steps
- Custom fields
  - Creating a field class
  - Method fields
  - Function fields
  - `Method` and `Function` field deserialization
  - Adding context to `Method` and `Function` fields
  - Customizing error messages
  - Next steps
- Extending schemas
  - Pre-processing and post-processing methods
  - Schema-level validation
  - Using original input data
  - Overriding how attributes are accessed
  - Custom error handling
  - Custom `class Meta` options
  - Using context
  - Custom error messages
- Examples
  - Validating `package.json`
  - Quotes API (Flask + SQLAlchemy)
  - Inflection (camel-cased keys)

## API reference

API reference

- Top-level API
- Schema
- Fields
- Decorators
- Validators
- Utility functions
- Exceptions
- Private API

## Project info

Project info

- Why marshmallow?
- Changelog
- Upgrading to newer releases
- Who’s using marshmallow?
- License
- Authors
- Contributing guidelines
- Code of Conduct
- Kudos
- Donate