Registry / serialization / apispec-oneofschema

apispec-oneofschema

library3.0.2pypypi✓ verified 85d ago

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.

serialization web-framework

pip install apispec-oneofschema

github ↗package ↗

INSTALL

IMPORT

SIG · APISPEC-ONEOFSCHEM

apispec-oneofschema

serializationpythonv3.0.2

Install

1.9s avg

Import

606ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.0.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.613s · 19.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.9s · import 0.599s · 20MB

18MB installed

● package 18MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MarshmallowPlugin

✓ from apispec_oneofschema import MarshmallowPlugin

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.

from apispec import APISpec from marshmallow import Schema, fields from marshmallow_oneofschema import OneOfSchema from apispec_oneofschema import MarshmallowPlugin class TreeSchema(Schema): leaves = fields.Int(required=True) class FlowerSchema(Schema): blooming = fields.Bool(required=True) class PlantSchema(OneOfSchema): type_schemas = { 'tree': TreeSchema, 'flower': FlowerSchema } spec = APISpec( title='Botany', version='1.0.0', openapi_version='3.0.0', # Must be 3.0.0 or greater plugins=[ MarshmallowPlugin(), ] ) spec.components.schema('Plant', schema=PlantSchema) spec.components.schema('Tree', schema=TreeSchema) spec.components.schema('Flower', schema=FlowerSchema) # Optional: Add schemas that are part of OneOfSchema directly to components # spec.components.schema('Tree', schema=TreeSchema) # spec.components.schema('Flower', schema=FlowerSchema) print(spec.to_yaml())

Debug

Known issues

breakingThis 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.

fix

Ensure `openapi_version` is set to '3.0.0' or higher when initializing `APISpec`.

affects: All versions

gotchaWhen 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.

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.

affects: All versions

gotchaThere 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.

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.

affects: apispec versions 0.x to 6.x

Errors

Common errors & fixes

DuplicateComponentNameError: Another schema with name "SchemaA" is already registered.

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.

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.

OpenAPI documentation does not show 'oneOf' schemas or discriminator properties for `Marshmallow-OneOfSchema`.

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.

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).

Upgrade

Version history

3.0.2latest on PyPI · released Jul 28, 2025

Audit

Dependencies

apispecrequiredThis is a plugin for apispec, requiring it for core functionality and API specification generation.

marshmallow-oneofschemarequiredThis plugin provides support for schemas defined using marshmallow-oneofschema, making it a core dependency.

marshmallowrequiredMarshmallow is a dependency of marshmallow-oneofschema, and apispec's MarshmallowPlugin also requires specific versions (>=3.13.0 for apispec 6.x).

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/timakro/apispec-oneofschema ↗

packagehttps://pypi.org/project/apispec-oneofschema/ ↗