apispec-oneofschema

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 on this page — 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

apispec-oneofschema on PyPI

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

Evidence: apispec_oneofschema-3.0.2-py3-none-any.whl

Tags

More Application Frameworks packages