API Reference

Classes:

Schema(*[, only, exclude, many, context, ...])

Base schema class with which to define custom schemas.

SchemaOpts(meta[, ordered])

class Meta options for the Schema.

Exceptions:

ValidationError(message[, field_name, data, ...])

Raised when validation fails on a field or schema.

Functions:

post_dump([fn, pass_many, pass_original])

Register a method to invoke after serializing an object.

post_load([fn, pass_many, pass_original])

Register a method to invoke after deserializing an object.

pprint(obj, *args, **kwargs)

Pretty-printing function that can pretty-print OrderedDicts like regular dictionaries.

pre_dump([fn, pass_many])

Register a method to invoke before serializing an object.

pre_load([fn, pass_many])

Register a method to invoke before deserializing an object.

validates(field_name)

Register a field validator.

validates_schema([fn, pass_many, ...])

Register a schema-level validator.
class marshmallow.Schema(*, only: Optional[Union[Sequence[str], Set[str]]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Optional[Dict] = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: Optional[str] = None)[source]

Base schema class with which to define custom schemas.

Example usage:

import datetime as dt
from dataclasses import dataclass

from marshmallow import Schema, fields


@dataclass
class Album:
    title: str
    release_date: dt.date


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


album = Album("Beggars Banquet", dt.date(1968, 12, 6))
schema = AlbumSchema()
data = schema.dump(album)
data  # {'release_date': '1968-12-06', 'title': 'Beggars Banquet'}
Parameters

  • only – Whitelist of the declared fields to select when instantiating the Schema. If None, all fields are used. Nested fields can be represented with dot delimiters.

  • exclude – Blacklist of the declared fields to exclude when instantiating the Schema. If a field appears in both only and exclude, it is not used. Nested fields can be represented with dot delimiters.

  • many – Should be set to True if obj is a collection so that the object will be serialized to a list.

  • context – Optional context passed to fields.Method and fields.Function fields.

  • load_only – Fields to skip during serialization (write-only fields)

  • dump_only – Fields to skip during deserialization (read-only fields)

  • partial – Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.

  • unknown – Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE.

Changed in version 3.0.0: prefix parameter removed.

Changed in version 2.0.0: __validators__, __preprocessors__, and __data_handlers__ are removed in favor of marshmallow.decorators.validates_schema, marshmallow.decorators.pre_load and marshmallow.decorators.post_dump. __accessor__ and __error_handler__ are deprecated. Implement the handle_error and get_attribute methods instead.

Classes:

Meta()

Options object for a Schema.

OPTIONS_CLASS

alias of marshmallow.schema.SchemaOpts

Attributes:

TYPE_MAPPING

dict_class

error_messages

Overrides for default schema-level error messages

fields

Dictionary mapping field_names -> Field objects

opts

set_class

Methods:

dump(obj, *[, many])

Serialize an object to native Python data types according to this Schema's fields.

dumps(obj, *args[, many])

Same as dump(), except return a JSON-encoded string.

from_dict(fields, *[, name])

Generate a Schema class given a dictionary of fields.

get_attribute(obj, attr, default)

Defines how to pull values from an object to serialize.

handle_error(error, data, *, many, **kwargs)

Custom error handler function for the schema.

load(data, *[, many, partial, unknown])

Deserialize a data structure to an object defined by this Schema's fields.

loads(json_data, *[, many, partial, unknown])

Same as load(), except it takes a JSON string as input.

on_bind_field(field_name, field_obj)

Hook to modify a field when it is bound to the Schema.

validate(data, *[, many, partial])

Validate data against the schema, returning a dictionary of validation errors.
class Meta[source]

Options object for a Schema.

Example usage:

class Meta:
    fields = ("id", "email", "date_created")
    exclude = ("password", "secret_attribute")

Available options:

  • fields: Tuple or list of fields to include in the serialized result.

  • additional: Tuple or list of fields to include in addition to the

    explicitly declared fields. additional and fields are mutually-exclusive options.

  • include: Dictionary of additional fields to include in the schema. It is

    usually better to define fields as class variables, but you may need to use this option, e.g., if your fields are Python keywords. May be an OrderedDict.

  • exclude: Tuple or list of fields to exclude in the serialized result.

    Nested fields can be represented with dot delimiters.

  • dateformat: Default format for Date fields.

  • datetimeformat: Default format for DateTime fields.

  • timeformat: Default format for Time fields.

  • render_module: Module to use for loads and dumps.

    Defaults to json from the standard library.

  • ordered: If True, order serialization output according to the

    order in which fields were declared. Output of Schema.dump will be a collections.OrderedDict.

  • index_errors: If True, errors dictionaries will include the index

    of invalid items in a collection.

  • load_only: Tuple or list of fields to exclude from serialized results.

  • dump_only: Tuple or list of fields to exclude from deserialization

  • unknown: Whether to exclude, include, or raise an error for unknown

    fields in the data. Use EXCLUDE, INCLUDE or RAISE.

  • register: Whether to register the Schema with marshmallow’s internal

    class registry. Must be True if you intend to refer to this Schema by class name in Nested fields. Only set this to False when memory usage is critical. Defaults to True.

OPTIONS_CLASS

alias of marshmallow.schema.SchemaOpts

TYPE_MAPPING = {<class 'str'>: <class 'marshmallow.fields.String'>, <class 'bytes'>: <class 'marshmallow.fields.String'>, <class 'datetime.datetime'>: <class 'marshmallow.fields.DateTime'>, <class 'float'>: <class 'marshmallow.fields.Float'>, <class 'bool'>: <class 'marshmallow.fields.Boolean'>, <class 'tuple'>: <class 'marshmallow.fields.Raw'>, <class 'list'>: <class 'marshmallow.fields.Raw'>, <class 'set'>: <class 'marshmallow.fields.Raw'>, <class 'int'>: <class 'marshmallow.fields.Integer'>, <class 'uuid.UUID'>: <class 'marshmallow.fields.UUID'>, <class 'datetime.time'>: <class 'marshmallow.fields.Time'>, <class 'datetime.date'>: <class 'marshmallow.fields.Date'>, <class 'datetime.timedelta'>: <class 'marshmallow.fields.TimeDelta'>, <class 'decimal.Decimal'>: <class 'marshmallow.fields.Decimal'>}
property dict_class: type
dump(obj: Any, *, many: Optional[bool] = None)[source]

Serialize an object to native Python data types according to this Schema’s fields.

Parameters

  • obj – The object to serialize.

  • many – Whether to serialize obj as a collection. If None, the value for self.many is used.

Returns

Serialized data

New in version 1.0.0.

Changed in version 3.0.0b7: This method returns the serialized data rather than a (data, errors) duple. A ValidationError is raised if obj is invalid.

Changed in version 3.0.0rc9: Validation no longer occurs upon serialization.

dumps(obj: Any, *args, many: Optional[bool] = None, **kwargs)[source]

Same as dump(), except return a JSON-encoded string.

Parameters

  • obj – The object to serialize.

  • many – Whether to serialize obj as a collection. If None, the value for self.many is used.

Returns

A json string

New in version 1.0.0.

Changed in version 3.0.0b7: This method returns the serialized data rather than a (data, errors) duple. A ValidationError is raised if obj is invalid.

error_messages = {}

Overrides for default schema-level error messages

fields

Dictionary mapping field_names -> Field objects

classmethod from_dict(fields: Dict[str, Union[marshmallow.fields.Field, type]], *, name: str = 'GeneratedSchema') → type[source]

Generate a Schema class given a dictionary of fields.

from marshmallow import Schema, fields

PersonSchema = Schema.from_dict({"name": fields.Str()})
print(PersonSchema().load({"name": "David"}))  # => {'name': 'David'}

Generated schemas are not added to the class registry and therefore cannot be referred to by name in Nested fields.

Parameters

  • fields (dict) – Dictionary mapping field names to field instances.

  • name (str) – Optional name for the class, which will appear in the repr for the class.

New in version 3.0.0.

get_attribute(obj: Any, attr: str, default: Any)[source]

Defines how to pull values from an object to serialize.

New in version 2.0.0.

Changed in version 3.0.0a1: Changed position of obj and attr.

handle_error(error: marshmallow.exceptions.ValidationError, data: Any, *, many: bool, **kwargs)[source]

Custom error handler function for the schema.

Parameters

  • error – The ValidationError raised during (de)serialization.

  • data – The original input data.

  • many – Value of many on dump or load.

  • partial – Value of partial on load.

New in version 2.0.0.

Changed in version 3.0.0rc9: Receives many and partial (on deserialization) as keyword arguments.

load(data: Union[Mapping[str, Any], Iterable[Mapping[str, Any]]], *, many: Optional[bool] = None, partial: Optional[Union[bool, Sequence[str], Set[str]]] = None, unknown: Optional[str] = None)[source]

Deserialize a data structure to an object defined by this Schema’s fields.

Parameters

  • data – The data to deserialize.

  • many – Whether to deserialize data as a collection. If None, the value for self.many is used.

  • partial – Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.

  • unknown – Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE. If None, the value for self.unknown is used.

Returns

Deserialized data

New in version 1.0.0.

Changed in version 3.0.0b7: This method returns the deserialized data rather than a (data, errors) duple. A ValidationError is raised if invalid data are passed.

loads(json_data: str, *, many: Optional[bool] = None, partial: Optional[Union[bool, Sequence[str], Set[str]]] = None, unknown: Optional[str] = None, **kwargs)[source]

Same as load(), except it takes a JSON string as input.

Parameters

  • json_data – A JSON string of the data to deserialize.

  • many – Whether to deserialize obj as a collection. If None, the value for self.many is used.

  • partial – Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.

  • unknown – Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE. If None, the value for self.unknown is used.

Returns

Deserialized data

New in version 1.0.0.

Changed in version 3.0.0b7: This method returns the deserialized data rather than a (data, errors) duple. A ValidationError is raised if invalid data are passed.

on_bind_field(field_name: str, field_obj: marshmallow.fields.Field) → None[source]

Hook to modify a field when it is bound to the Schema.

No-op by default.

opts = <marshmallow.schema.SchemaOpts object>
property set_class: type
validate(data: Mapping, *, many: Optional[bool] = None, partial: Optional[Union[bool, Sequence[str], Set[str]]] = None) → Dict[str, List[str]][source]

Validate data against the schema, returning a dictionary of validation errors.

Parameters

  • data – The data to validate.

  • many – Whether to validate data as a collection. If None, the value for self.many is used.

  • partial – Whether to ignore missing fields and not require any fields declared. Propagates down to Nested fields as well. If its value is an iterable, only missing fields listed in that iterable will be ignored. Use dot delimiters to specify nested fields.

Returns

A dictionary of validation errors.

New in version 1.1.0.

class marshmallow.SchemaOpts(meta, ordered: bool = False)[source]

class Meta options for the Schema. Defines defaults.

exception marshmallow.ValidationError(message: Union[str, List, Dict], field_name: str = '_schema', data: Optional[Union[Mapping[str, Any], Iterable[Mapping[str, Any]]]] = None, valid_data: Optional[Union[List[Dict[str, Any]], Dict[str, Any]]] = None, **kwargs)[source]

Raised when validation fails on a field or schema.

Validators and custom fields should raise this exception.

Parameters

  • message – An error message, list of error messages, or dict of error messages. If a dict, the keys are subitems and the values are error messages.

  • field_name – Field name to store the error on. If None, the error is stored as schema-level error.

  • data – Raw input data.

  • valid_data – Valid (de)serialized data.

normalized_messages()[source]
marshmallow.post_dump(fn=None, pass_many=False, pass_original=False)[source]

Register a method to invoke after serializing an object. The method receives the serialized object and returns the processed object.

By default it receives a single object at a time, transparently handling the many argument passed to the Schema’s dump() call. If pass_many=True, the raw data (which may be a collection) is passed.

If pass_original=True, the original data (before serializing) will be passed as an additional argument to the method.

Changed in version 3.0.0: many is always passed as a keyword arguments to the decorated method.

marshmallow.post_load(fn=None, pass_many=False, pass_original=False)[source]

Register a method to invoke after deserializing an object. The method receives the deserialized data and returns the processed data.

By default it receives a single object at a time, transparently handling the many argument passed to the Schema’s load() call. If pass_many=True, the raw data (which may be a collection) is passed.

If pass_original=True, the original data (before deserializing) will be passed as an additional argument to the method.

Changed in version 3.0.0: partial and many are always passed as keyword arguments to the decorated method.

marshmallow.pprint(obj, *args, **kwargs) → None[source]

Pretty-printing function that can pretty-print OrderedDicts like regular dictionaries. Useful for printing the output of marshmallow.Schema.dump().

Deprecated since version 3.7.0: marshmallow.pprint will be removed in marshmallow 4.

marshmallow.pre_dump(fn=None, pass_many=False)[source]

Register a method to invoke before serializing an object. The method receives the object to be serialized and returns the processed object.

By default it receives a single object at a time, transparently handling the many argument passed to the Schema’s dump() call. If pass_many=True, the raw data (which may be a collection) is passed.

Changed in version 3.0.0: many is always passed as a keyword arguments to the decorated method.

marshmallow.pre_load(fn=None, pass_many=False)[source]

Register a method to invoke before deserializing an object. The method receives the data to be deserialized and returns the processed data.

By default it receives a single object at a time, transparently handling the many argument passed to the Schema’s load() call. If pass_many=True, the raw data (which may be a collection) is passed.

Changed in version 3.0.0: partial and many are always passed as keyword arguments to the decorated method.

marshmallow.validates(field_name: str)[source]

Register a field validator.

Parameters

field_name (str) – Name of the field that the method validates.

marshmallow.validates_schema(fn=None, pass_many=False, pass_original=False, skip_on_field_errors=True)[source]

Register a schema-level validator.

By default it receives a single object at a time, transparently handling the many argument passed to the Schema’s validate() call. If pass_many=True, the raw data (which may be a collection) is passed.

If pass_original=True, the original data (before unmarshalling) will be passed as an additional argument to the method.

If skip_on_field_errors=True, this validation method will be skipped whenever validation errors have been detected when validating fields.

Changed in version 3.0.0b1: skip_on_field_errors defaults to True.

Changed in version 3.0.0: partial and many are always passed as keyword arguments to the decorated method.

marshmallow.EXCLUDE
marshmallow.INCLUDE
marshmallow.RAISE
marshmallow.missing