{"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":"python","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,"search_vec":"'3.2.0':33 'allow':12 'base':24 'cadenc':39 'capabl':9 'core':42 'current':30 'data':57 'deseri':19,54 'differ':22 'discrimin':27 'field':28 'follow':36 'librari':44 'marshmallow':1,4,11,43,52 'marshmallow-oneofschema':3 'object':20 'oneofschema':2,5 'polymorph':7,55 'provid':6 'releas':38,51 'schema':8,15,56 'serial':17,53 'singl':14 'stabl':46 'test':50 'type':23 'valid':58 'version':31 'well':49 'well-test':48","created_at":"2026-04-09T03:52:46.107215+00:00","updated_at":"2026-04-16T16:27:19.096724+00:00","problems":[{"fix":"Install the library using pip: `pip install marshmallow-oneofschema`","cause":"The `marshmallow-oneofschema` library has not been installed in your Python environment.","error":"ModuleNotFoundError: No module named 'marshmallow_oneofschema'"},{"fix":"Upgrade `marshmallow-oneofschema` to version 3.0.0 or higher to ensure compatibility with Marshmallow 3+: `pip install --upgrade marshmallow-oneofschema`","cause":"This error typically occurs when using an older version of `marshmallow-oneofschema` (e.g., pre-3.0.0) with Marshmallow 3.x or newer. `MarshalResult` and `UnmarshalResult` were removed from the top-level `marshmallow` import in Marshmallow 3.","error":"ImportError: cannot import name 'MarshalResult' from 'marshmallow'"},{"fix":"Ensure that the input data's discriminator field value (e.g., `{'type': 'UnknownType'}`) exactly matches a key in your `OneOfSchema`'s `type_schemas` dictionary. Also, verify the discriminator field name (`type_field`) matches the field in your input data.","cause":"This validation error occurs during deserialization when the value provided for the discriminator field (e.g., 'type') does not match any of the keys defined in the `type_schemas` mapping of your `OneOfSchema`.","error":"ValidationError: {'<discriminator_field>': ['<discriminator_field> has unknown type <value>']}"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.2.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/marshmallow-code/marshmallow-oneofschema","docs":null,"changelog":null,"pypi":"https://pypi.org/project/marshmallow-oneofschema/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}