Basic Usage¶

This guide covers the bridge-specific APIs. For underlying features, see:

Creating Schemas¶

Using `schema_for()`¶

The simplest way to create a schema:

from pydantic import BaseModel
from pydantic_marshmallow import schema_for

class User(BaseModel):
    name: str
    email: str

UserSchema = schema_for(User)
schema = UserSchema()

Using `PydanticSchema` Class¶

For more control, subclass PydanticSchema:

from pydantic_marshmallow import PydanticSchema

class UserSchema(PydanticSchema[User]):
    class Meta:
        model = User

Using `from_model()` with Options¶

Create schemas with field filtering:

# Only include specific fields
LimitedSchema = PydanticSchema.from_model(User, fields=("name", "email"))

# Exclude specific fields
FilteredSchema = PydanticSchema.from_model(User, exclude=("password",))

Loading Data¶

Basic Load¶

schema = UserSchema()
user = schema.load({"name": "Alice", "email": "alice@example.com"})

Load as Dict (not model instance)¶

data = schema.load({"name": "Alice", "email": "alice@example.com"}, return_instance=False)
# Returns dict instead of User instance

Load Many¶

schema = UserSchema(many=True)
users = schema.load([
    {"name": "Alice", "email": "alice@example.com"},
    {"name": "Bob", "email": "bob@example.com"}
])

Partial Loading¶

Allow missing required fields:

# All fields optional
user = schema.load({"name": "Alice"}, partial=True)

# Only specific fields optional
user = schema.load({"name": "Alice"}, partial=("email",))

Serializing Data¶

Basic Dump¶

data = schema.dump(user)

Dump Options¶

# Exclude None values
data = schema.dump(user, exclude_none=True)

# Exclude unset fields (never assigned)
data = schema.dump(user, exclude_unset=True)

# Exclude fields equal to their default
data = schema.dump(user, exclude_defaults=True)

Dump to JSON¶

json_str = schema.dumps(user)

Unknown Field Handling¶

Control how unknown fields are handled (standard Marshmallow behavior):

from marshmallow import RAISE, EXCLUDE, INCLUDE

# Reject unknown fields (default)
schema = UserSchema(unknown=RAISE)

# Silently remove unknown fields
schema = UserSchema(unknown=EXCLUDE)

# Include unknown fields in result
schema = UserSchema(unknown=INCLUDE)

See Marshmallow: Handling Unknown Fields for details.

Validation Without Loading¶

Get validation errors without deserializing:

errors = schema.validate({"name": "", "email": "invalid"})
if errors:
    print(errors)  # {'name': [...], 'email': [...]}
else:
    print("Valid!")