marshmallow-fastoneofschema

2025.9.2.1.dev7 verified Fri May 01 auth: no python

A fast multiplexing schema for marshmallow that dispatches deserialization to a subschema based on a discriminator field. Uses schema caching for speed. Current version (2025.9.2.1.dev7) is a development release; requires Python >=3.11.

pip install marshmallow-fastoneofschema

Common errors

error ImportError: cannot import name 'FastOneOfSchema' from 'marshmallow_fastoneofschema' ↓

cause Old version or incorrect library installed (e.g., same name but different package).

fix

Run pip install --upgrade marshmallow-fastoneofschema and ensure you have a recent version (>=2025.9.2.1.dev0).

error marshmallow.exceptions.ValidationError: {'_schema': ['Invalid type field value']} ↓

cause The discriminator field value does not match any key in `type_schemas`.

fix

Check that the input contains a valid discriminator value, e.g., one of the keys defined in type_schemas.

Warnings

gotcha The `type_field` must be present in the input data and must match one of the keys in `type_schemas`. Missing or mismatched values cause a validation error. ↓

fix Ensure each input dict contains the discriminator field with a valid value.

gotcha FastOneOfSchema caches the mapping from type_field value to schema. If you mutate `type_schemas` after instantiation, the cache may become stale. ↓

fix Define `type_schemas` as a class variable or set it before any call to load/dump.

deprecated Previously, the discriminator field was set via `type_field` as a class variable. Some older examples used `type_field_` (with underscore). The correct attribute is `type_field`. ↓

fix Use `type_field` (without trailing underscore) as the class variable or constructor argument.

Imports

FastOneOfSchema

from marshmallow_fastoneofschema import FastOneOfSchema

Quickstart

Demonstrates basic usage: define a FastOneOfSchema with a discriminator field and subschemas.

from marshmallow import Schema, fields
from marshmallow_fastoneofschema import FastOneOfSchema

class CarSchema(Schema):
    make = fields.String(required=True)
    model = fields.String(required=True)

class BoatSchema(Schema):
    length = fields.Float(required=True)

class VehicleSchema(FastOneOfSchema):
    type_field = 'vehicle_type'
    type_schemas = {
        'car': CarSchema,
        'boat': BoatSchema
    }

schema = VehicleSchema()
data = {'vehicle_type': 'car', 'make': 'Toyota', 'model': 'Camry'}
result = schema.load(data)
print(result)  # => {'vehicle_type': 'car', 'make': 'Toyota', 'model': 'Camry'}