{"id":1546,"library":"marshmallow-oneofschema","title":"Marshmallow OneOfSchema","description":"marshmallow-oneofschema provides polymorphic schema capabilities for Marshmallow, allowing a single schema to serialize and deserialize objects of different types based on a discriminator field. The current version is 3.2.0, and it follows the release cadence of the core Marshmallow library, with stable and well-tested releases.","status":"active","version":"3.2.0","language":"en","source_language":"en","source_url":"https://github.com/marshmallow-code/marshmallow-oneofschema","tags":["marshmallow","serialization","deserialization","polymorphism","schema","data validation"],"install":[{"cmd":"pip install marshmallow-oneofschema","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for schema definition and processing.","package":"marshmallow","optional":false}],"imports":[{"symbol":"OneOfSchema","correct":"from marshmallow_oneofschema import OneOfSchema"}],"quickstart":{"code":"from marshmallow import Schema, fields\nfrom marshmallow_oneofschema import OneOfSchema\n\nclass CatSchema(Schema):\n    name = fields.String(required=True)\n    lives = fields.Integer(load_default=9)\n\nclass DogSchema(Schema):\n    name = fields.String(required=True)\n    breed = fields.String()\n\nclass PetSchema(OneOfSchema):\n    type_schemas = {\n        \"cat\": CatSchema,\n        \"dog\": DogSchema,\n    }\n    type_field = \"pet_type\" # Discriminator field in input data\n\n# Example data\ncat_data = {\"pet_type\": \"cat\", \"name\": \"Whiskers\", \"lives\": 7}\ndog_data = {\"pet_type\": \"dog\", \"name\": \"Buddy\", \"breed\": \"Golden Retriever\"}\nunknown_pet_data = {\"pet_type\": \"fish\", \"name\": \"Nemo\"}\n\n# Instantiate the polymorphic schema\npet_schema = PetSchema()\n\n# Serialization (dump)\nserialized_cat = pet_schema.dump(cat_data)\nprint(f\"Serialized Cat: {serialized_cat}\")\n\nserialized_dog = pet_schema.dump(dog_data)\nprint(f\"Serialized Dog: {serialized_dog}\")\n\n# Deserialization (load)\nloaded_cat = pet_schema.load(serialized_cat)\nprint(f\"Loaded Cat: {loaded_cat}\")\n\nloaded_dog = pet_schema.load(serialized_dog)\nprint(f\"Loaded Dog: {loaded_dog}\")\n\ntry:\n    # This will raise a ValidationError because 'fish' is not in type_schemas\n    pet_schema.load(unknown_pet_data)\nexcept Exception as e:\n    print(f\"Error loading unknown type: {e}\")","lang":"python","description":"This quickstart demonstrates how to define a `OneOfSchema` to handle different types of pet objects (Cat and Dog). It shows how to map type identifiers to specific Marshmallow schemas using `type_schemas` and how to specify the discriminator field using `type_field`. It also includes examples of both serialization (`dump`) and deserialization (`load`), and demonstrates handling an unknown type during deserialization."},"warnings":[{"fix":"Ensure your project's Marshmallow dependency is `marshmallow>=3.0.0`. Upgrade Marshmallow if necessary (e.g., `pip install 'marshmallow>=3.0.0'`).","message":"marshmallow-oneofschema v2.0.0 and later require Marshmallow v3.x. Attempting to use it with Marshmallow v2.x will result in `ImportError` or other runtime errors due to API changes in Marshmallow.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"If migrating from v1.x, update your schema definition from `type_map = {'type_name': SchemaClass}` to `type_schemas = {'type_name': SchemaClass}` and explicitly set `type_field = 'discriminator_field_name'`.","message":"The API for defining polymorphic schemas changed significantly in v2.0.0. The `type_map` attribute was removed and replaced by `type_schemas` and `type_field` for clearer definition of type mappings and the discriminator field.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always define `type_field` in your `OneOfSchema` subclass, ensuring it matches the field name in your input data that determines the object's type. For input data, make sure the `type_field` is present and its value exactly matches a key in `type_schemas`.","message":"Incorrectly specifying or omitting the `type_field` attribute or providing data without this field will lead to deserialization failures (`ValidationError`), as `OneOfSchema` won't know which sub-schema to use.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure all possible object types that your `OneOfSchema` might encounter are explicitly listed as keys in `type_schemas`, mapped to their respective Marshmallow schema classes. Handle unknown types upstream if they are not expected to be processed by this schema.","message":"Attempting to serialize or deserialize an object whose type (as indicated by `type_field`) is not present as a key in the `type_schemas` dictionary will result in an error (`ValueError` for dump, `ValidationError` for load).","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}