---
id: apispec-oneofschema
version: "3.0.2"
license: MIT
license_treatment: permissive
maintenance: aging
---

# apispec-oneofschema — Plugin for apispec providing support for Marshmallow-OneOfSchema schemas

License: permissive · Maintenance: aging · Downloads: 237.7K/mo

## What it is and what it does

apispec-oneofschema is a plugin for apispec that bridges Marshmallow's OneOfSchema polymorphic type system with OpenAPI 3.0+ documentation. It automatically generates discriminator-based schema definitions in your OpenAPI spec, mapping polymorphic types to their corresponding schemas with proper references.

When you register a OneOfSchema with apispec using this plugin, it produces OpenAPI components that include a discriminator object with a propertyName and a mapping of type values to schema references. This lets API consumers understand which schema variant applies based on a discriminator field in the JSON payload, and it enables code generation tools to handle polymorphic responses correctly.

Use it for:

- Document REST APIs with polymorphic request or response bodies where the type is determined by a discriminator field.
- Generate OpenAPI specs for services using Marshmallow OneOfSchema for type-safe serialization of union types.
- Enable API client generators to produce correct deserialization code for discriminator-based polymorphic types.
- Validate and document complex data models with multiple schema variants in a single endpoint.
- Integrate Marshmallow schema definitions directly into OpenAPI documentation without manual discriminator mapping.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Extends apispec to generate OpenAPI 3.0+ documentation for Marshmallow OneOfSchema schemas, mapping polymorphic types to discriminator-based schema references.

Yes, if you use Marshmallow OneOfSchema and need to generate OpenAPI 3.0+ documentation. The plugin fills a specific gap—apispec does not natively handle OneOfSchema discriminators—and has no known vulnerabilities. The aging maintenance status is a minor concern but not a blocker for a stable, focused tool. Install if this matches your stack; skip if you don't use OneOfSchema or target earlier OpenAPI versions.

## Install

pip install apispec-oneofschema
uv add apispec-oneofschema
poetry add apispec-oneofschema

## Installing apispec-oneofschema

Before you install: Low friction installation with three straightforward runtime dependencies. Maintenance status is aging—last release was 382 days ago—but the repository remains active and unarchived, suggesting the package is stable rather than abandoned.

License in practice: MIT license is permissive, allowing use in commercial and proprietary projects with minimal restrictions beyond attribution.

Quickstart:

pip install apispec-oneofschema

from apispec import APISpec
from apispec_oneofschema import MarshmallowPlugin
from marshmallow_oneofschema import OneOfSchema

spec = APISpec(
    title='Example',
    version='1.0.0',
    openapi_version='3.0.0',
    plugins=[MarshmallowPlugin()]
)
spec.components.schema('MySchema', schema=YourOneOfSchema)

Requires OpenAPI version 3.0.0 or greater; earlier versions do not support discriminator name-to-definition mapping.

Verify before relying:

- Whether the package works with current versions of apispec and marshmallow-oneofschema without breaking changes.
- Python version compatibility (requires_python is unspecified in metadata).

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 237.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

apispec marshmallow plugin, openapi oneof schema, polymorphic schema documentation, marshmallow discriminator, api spec schema generation, openapi 3.0 discriminator, openapi-generation, schema-validation

[View on SkillFed](https://skillfed.io/packages/apispec-oneofschema) · [View on PyPI](https://pypi.org/project/apispec-oneofschema/)