{"id":6991,"library":"apispec-oneofschema","title":"apispec-oneofschema","description":"apispec-oneofschema is a plugin for apispec that extends its functionality to provide support for Marshmallow-OneOfSchema schemas. It enables the generation of OpenAPI documentation for polymorphic schemas defined using marshmallow-oneofschema. The current version is 3.0.2, and it is actively maintained.","status":"active","version":"3.0.2","language":"en","source_language":"en","source_url":"https://github.com/timakro/apispec-oneofschema","tags":["apispec","marshmallow","openapi","swagger","schema","polymorphism","oneof"],"install":[{"cmd":"pip install apispec-oneofschema","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This is a plugin for apispec, requiring it for core functionality and API specification generation.","package":"apispec"},{"reason":"This plugin provides support for schemas defined using marshmallow-oneofschema, making it a core dependency.","package":"marshmallow-oneofschema"},{"reason":"Marshmallow is a dependency of marshmallow-oneofschema, and apispec's MarshmallowPlugin also requires specific versions (>=3.13.0 for apispec 6.x).","package":"marshmallow"}],"imports":[{"symbol":"MarshmallowPlugin","correct":"from apispec_oneofschema import MarshmallowPlugin"}],"quickstart":{"code":"from apispec import APISpec\nfrom marshmallow import Schema, fields\nfrom marshmallow_oneofschema import OneOfSchema\nfrom apispec_oneofschema import MarshmallowPlugin\n\nclass TreeSchema(Schema):\n    leaves = fields.Int(required=True)\n\nclass FlowerSchema(Schema):\n    blooming = fields.Bool(required=True)\n\nclass PlantSchema(OneOfSchema):\n    type_schemas = {\n        'tree': TreeSchema,\n        'flower': FlowerSchema\n    }\n\nspec = APISpec(\n    title='Botany',\n    version='1.0.0',\n    openapi_version='3.0.0', # Must be 3.0.0 or greater\n    plugins=[\n        MarshmallowPlugin(),\n    ]\n)\n\nspec.components.schema('Plant', schema=PlantSchema)\nspec.components.schema('Tree', schema=TreeSchema)\nspec.components.schema('Flower', schema=FlowerSchema)\n\n# Optional: Add schemas that are part of OneOfSchema directly to components\n# spec.components.schema('Tree', schema=TreeSchema)\n# spec.components.schema('Flower', schema=FlowerSchema)\n\nprint(spec.to_yaml())","lang":"python","description":"This quickstart demonstrates how to define a polymorphic schema using `marshmallow-oneofschema.OneOfSchema` and then integrate it with `apispec` using `apispec-oneofschema.MarshmallowPlugin` to generate an OpenAPI specification. Ensure `openapi_version` is set to '3.0.0' or greater."},"warnings":[{"fix":"Ensure `openapi_version` is set to '3.0.0' or higher when initializing `APISpec`.","message":"This plugin only supports OpenAPI Specification version 3.0.0 or greater. It relies on features like the `discriminator` which were introduced in OpenAPI 3.0.0.","severity":"breaking","affected_versions":"All versions"},{"fix":"Manually register common sub-schemas only once via `spec.components.schema()` before registering the `OneOfSchema` instances. Alternatively, catch and handle `DuplicateComponentNameError` if the duplicate component is guaranteed to be identical.","message":"When registering multiple `OneOfSchema` instances that share common sub-schemas (e.g., `SchemaA` in both `SchemaAorB` and `SchemaAorC`), `apispec` may raise a `DuplicateComponentNameError` if the shared schema is registered implicitly more than once.","severity":"gotcha","affected_versions":"All versions"},{"fix":"There is no direct user fix. Check the `apispec` and `apispec-oneofschema` GitHub repositories for updates on Issue #1012, or potential workarounds/newer versions that address this.","message":"There is an open issue in `apispec` (Issue #1012) where `apispec` might ignore `oneOf` definitions coming from `marshmallow-oneofschema`, leading to incomplete or incorrect OpenAPI documentation for polymorphic schemas.","severity":"gotcha","affected_versions":"apispec versions 0.x to 6.x"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Explicitly register shared sub-schemas (like `SchemaA`) once with `spec.components.schema('SchemaA', schema=SchemaA)` *before* registering the `OneOfSchema`s that depend on it. This ensures it's only defined once.","cause":"Attempting to register multiple `OneOfSchema` instances that include the same underlying schema (e.g., `SchemaA` is part of both `SchemaAorB` and `SchemaAorC`). `apispec` attempts to register `SchemaA` multiple times during the processing of `OneOfSchema`s.","error":"DuplicateComponentNameError: Another schema with name \"SchemaA\" is already registered."},{"fix":"Verify that `openapi_version` in `APISpec` initialization is `'3.0.0'` or greater. If the issue persists, consult the GitHub issues for both `apispec` and `apispec-oneofschema` for potential workarounds or updates. Ensure `marshmallow-oneofschema` is correctly configured with `type_schemas` and `type_field` (if customizing).","cause":"The `apispec` library, specifically in combination with `apispec-oneofschema`, may not correctly process and render `oneOf` definitions due to an outstanding bug/issue (e.g., `apispec` Issue #1012). Also, ensure `openapi_version` is 3.0.0 or higher.","error":"OpenAPI documentation does not show 'oneOf' schemas or discriminator properties for `Marshmallow-OneOfSchema`."}]}