Schema¶

class marshmallow.schema.Schema(*, only=None, exclude=(), many=None, load_only=(), dump_only=(), partial=None, unknown=None)[source]¶

Base schema class with which to define 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 (types.StrSequenceOrSet | None) – 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 (types.StrSequenceOrSet) – 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 (bool | None) – Should be set to True if obj is a collection so that the object will be serialized to a list.
load_only (types.StrSequenceOrSet) – Fields to skip during serialization (write-only fields)
dump_only (types.StrSequenceOrSet) – Fields to skip during deserialization (read-only fields)
partial (bool | types.StrSequenceOrSet | None) – 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 (types.UnknownOption | None) – 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: Remove prefix parameter.

Changed in version 4.0.0: Remove context parameter.

Classes:

`Meta`	Options object for a Schema.
`dict_class`	`dict` type to return when serializing.
`set_class`	alias of `OrderedSet`

Methods:

`dump`	Serialize an object to native Python data types according to this Schema's fields.
`dumps`	Same as `dump()`, except return a JSON-encoded string.
`from_dict`	Generate a `Schema` class given a dictionary of fields.
`get_attribute`	Defines how to pull values from an object to serialize.
`handle_error`	Custom error handler function for the schema.
`load`	Deserialize a data structure to an object defined by this Schema's fields.
`loads`	Same as `load()`, except it uses `marshmallow.Schema.Meta.render_module` to deserialize the passed string before passing data to `load()`.
`on_bind_field`	Hook to modify a field when it is bound to the `Schema`.
`validate`	Validate `data` against the schema, returning a dictionary of validation errors.

Attributes:

`error_messages`	Overrides for default schema-level error messages
`fields`	Dictionary mapping field_names -> `Field` objects

class Meta[source]¶

Options object for a Schema.

Example usage:

from marshmallow import Schema


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

A note on type checking

Type checkers will only check the attributes of the Meta class if you explicitly subclass marshmallow.Schema.Meta.

from marshmallow import Schema


class MySchema(Schema):
    # Not checked by type checkers
    class Meta:
        additional = True


class MySchema2(Schema):
    # Type checkers will check attributes
    class Meta(Schema.Meta):
        additional = True  # Incompatible types in assignment

Removed in version 3.0.0b7: Remove strict.

Added in version 3.0.0b12: Add unknown.

Changed in version 3.0.0b17: Rename dateformat to datetimeformat.

Added in version 3.9.0: Add timeformat.

Changed in version 3.26.0: Deprecate ordered. Field order is preserved by default.

Removed in version 4.0.0: Remove ordered.

Attributes:

`additional`	Fields to include in addition to the explicitly declared fields.
`dateformat`	Default format for `Date` fields.
`datetimeformat`	Default format for `DateTime` fields.
`dump_only`	Fields to exclude from deserialized results
`exclude`	Fields to exclude in the serialized result.
`fields`	Fields to include in the (de)serialized result
`include`	Dictionary of additional fields to include in the schema.
`index_errors`	If `True`, errors dictionaries will include the index of invalid items in a collection.
`load_only`	Fields to exclude from serialized results
`many`	Whether data should be (de)serialized as a collection by default.
`register`	Whether to register the `Schema` with marshmallow's internal class registry.
`render_module`	Module to use for `loads` and `dumps`.
`timeformat`	Default format for `Time` fields.
`unknown`	Whether to exclude, include, or raise an error for unknown fields in the data.

additional: ClassVar[tuple[str, ...] | list[str]]¶: Fields to include in addition to the explicitly declared fields. additional and fields are mutually-exclusive options.

dateformat: ClassVar[str]¶: Default format for Date fields.

datetimeformat: ClassVar[str]¶: Default format for DateTime fields.

dump_only: ClassVar[tuple[str, ...] | list[str]]¶: Fields to exclude from deserialized results

exclude: ClassVar[tuple[str, ...] | list[str]]¶: Fields to exclude in the serialized result. Nested fields can be represented with dot delimiters.

fields: ClassVar[tuple[str, ...] | list[str]]¶: Fields to include in the (de)serialized result

include: ClassVar[dict[str, Field]]¶: 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.

index_errors: ClassVar[bool]¶: If True, errors dictionaries will include the index of invalid items in a collection.

load_only: ClassVar[tuple[str, ...] | list[str]]¶: Fields to exclude from serialized results

many: ClassVar[bool]¶: Whether data should be (de)serialized as a collection by default.

register: ClassVar[bool]¶: 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.

render_module: Any¶: Module to use for loads and dumps. Defaults to json from the standard library.

timeformat: ClassVar[str]¶: Default format for Time fields.

unknown: ClassVar[types.UnknownOption]¶: Whether to exclude, include, or raise an error for unknown fields in the data. Use EXCLUDE, INCLUDE or RAISE.

dict_class¶

dict type to return when serializing.

alias of dict

dump(obj, *, many=None)[source]¶

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

Parameters:

obj (Any) – The object to serialize.
many (bool | None) – Whether to serialize obj as a collection. If None, the value for self.many is used.

Returns:

Serialized data

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

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

dumps(obj, *args, many=None, **kwargs)[source]¶

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

Parameters:

obj (Any) – The object to serialize.
many (bool | None) – Whether to serialize obj as a collection. If None, the value for self.many is used.

Returns:

A json string

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

error_messages: dict[str, str] = {}¶: Overrides for default schema-level error messages

fields: dict[str, Field]¶: Dictionary mapping field_names -> Field objects

classmethod from_dict(fields, *, name='GeneratedSchema')[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[str, Field]) – Dictionary mapping field names to field instances.
name (str) – Optional name for the class, which will appear in the repr for the class.

Return type:

type[Schema]

Added in version 3.0.0.

get_attribute(obj, attr, default)[source]¶

Defines how to pull values from an object to serialize.

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

Parameters:

obj (Any)
attr (str)
default (Any)

handle_error(error, data, *, many, **kwargs)[source]¶

Custom error handler function for the schema.

Parameters:

error (ValidationError) – The ValidationError raised during (de)serialization.
data (Any) – The original input data.
many (bool) – Value of many on dump or load.
partial – Value of partial on load.

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

load(data, *, many=None, partial=None, unknown=None)[source]¶

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

Parameters:

data (Mapping[str, Any] | Sequence[Mapping[str, Any]]) – The data to deserialize.
many (bool | None) – Whether to deserialize data as a collection. If None, the value for self.many is used.
partial (bool | Sequence[str] | AbstractSet[str] | None) – 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 (Literal['exclude', 'include', 'raise'] | None) – 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

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

loads(s, /, *, many=None, partial=None, unknown=None, **kwargs)[source]¶

Same as load(), except it uses marshmallow.Schema.Meta.render_module to deserialize the passed string before passing data to load().

Parameters:

s (str | bytes | bytearray) – A string of the data to deserialize.
many (bool | None) – Whether to deserialize obj as a collection. If None, the value for self.many is used.
partial (bool | Sequence[str] | AbstractSet[str] | None) – 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 (Literal['exclude', 'include', 'raise'] | None) – 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

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

Changed in version 4.0.0: Rename json_module parameter to s.

on_bind_field(field_name, field_obj)[source]¶

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

No-op by default.

Parameters:

field_name (str)
field_obj (Field)

Return type:

None

set_class¶: alias of OrderedSet

validate(data, *, many=None, partial=None)[source]¶

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

Parameters:

data (Mapping[str, Any] | Sequence[Mapping[str, Any]]) – The data to validate.
many (bool | None) – Whether to validate data as a collection. If None, the value for self.many is used.
partial (bool | Sequence[str] | AbstractSet[str] | None) – 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.

Return type:

dict[str, list[str]]

class marshmallow.schema.SchemaOpts(meta)[source]¶

Defines defaults for marshmallow.Schema.Meta.

Parameters:: meta (type)