# marshmallow: simplified object serialization

Release v3.13.0. (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 tutorial 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.

## Guide

- Installation
  - Installing/Upgrading from the PyPI
  - Get the Bleeding Edge Version
- Quickstart
  - Declaring Schemas
  - Creating Schemas From Dictionaries
  - 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
  - Ordering Output
  - 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`
  - Text Analysis API (Bottle + TextBlob)
  - Quotes API (Flask + SQLAlchemy)
  - ToDo API (Flask + Peewee)
  - Inflection (Camel-casing Keys)

## API Reference

- API Reference
  - Schema
  - Fields
  - Decorators
  - Validators
  - Utility Functions
  - Error Store
  - Class Registry
  - Exceptions

## Project Info

- Why marshmallow?
- Changelog
- Upgrading to Newer Releases
- Ecosystem
- Who’s using marshmallow?
- License
- Authors
- Contributing Guidelines
- Code of Conduct
- Kudos