Registry / serialization / voluptuous-openapi

voluptuous-openapi

library0.3.0pypypi✓ verified 86d ago

voluptuous-openapi is a Python library that converts Voluptuous schemas into OpenAPI Schema objects. It is currently at version 0.3.0 and appears to have a stable, though not rapid, release cadence, with the latest release on Dec 30, 2025.

serialization

pip install voluptuous-openapi==0.3.0

github ↗package ↗

INSTALL

IMPORT

SIG · VOLUPTUOUS-OPENAPI

voluptuous-openapi

serializationpythonv0.3.0

Install

1.6s avg

Import

90ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.0 · 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.055s · 18.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.053s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

convert

✓ from voluptuous_openapi import convert

The primary function to convert Voluptuous schemas.

vol

✓ import voluptuous as vol

Common alias for the underlying voluptuous library for schema definition.

This quickstart demonstrates how to define a basic Voluptuous schema with required, optional, and type-specific validators, and then convert it into a dictionary representing an OpenAPI Schema object using `voluptuous-openapi.convert`.

import voluptuous as vol from voluptuous_openapi import convert # Define a simple Voluptuous schema schema = vol.Schema({ vol.Required('name'): vol.All(str, vol.Length(min=5)), vol.Optional('age'): vol.All(int, vol.Range(min=0)), 'email': vol.Email, }) # Convert the Voluptuous schema to an OpenAPI Schema object openapi_schema = convert(schema) # Print the resulting OpenAPI schema (dictionary representation) import json print(json.dumps(openapi_schema, indent=2))

Debug

Known issues

breakingOpenAPI Specification 3.1 introduced breaking changes compared to 3.0, notably replacing `nullable` with type arrays and aligning with JSON Schema Draft 2020-12. If `voluptuous-openapi` targets 3.0, users aiming for 3.1 might encounter compatibility issues or missing features.

fix

Verify the OpenAPI Specification version generated by `voluptuous-openapi` and ensure it matches the target environment. Manual adjustments to the generated schema may be required for full 3.1 compliance if not natively supported.

affects: OpenAPI Spec versions 3.0 vs 3.1

gotchaThe upstream `voluptuous` library, on which `voluptuous-openapi` depends, is in 'contributions only' mode, indicating that the original author is not actively developing new features or fixing bugs directly. This could impact the long-term evolution or responsiveness to new features/fixes for `voluptuous-openapi` related to underlying `voluptuous` capabilities.

fix

Be aware that feature requests or complex bug fixes requiring upstream changes in `voluptuous` might have limited support. Consider contributing fixes if critical issues arise.

affects: All versions

gotchaOpenAPI 3.0 had a known limitation where descriptions could not be directly provided alongside `$ref` references, making it difficult to fully document reusable components. If `voluptuous-openapi` generates 3.0-compliant schemas, this documentation gap might persist.

fix

For OpenAPI 3.0 targets, consider workarounds like the 'allOf hack' mentioned in community discussions, or upgrade to OpenAPI 3.1 if possible, which addresses this issue.

affects: OpenAPI Spec version 3.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'voluptuous_openapi'

The 'voluptuous-openapi' library has not been installed in the current Python environment.

fix

Run `pip install voluptuous-openapi` to install the package.

voluptuous.error.Invalid: extra keys not allowed @ data['unexpected_key']

The input data being validated by a Voluptuous schema contains keys that were not explicitly defined in the schema, and extra keys are not permitted by default.

fix

Modify your `voluptuous.Schema` definition to explicitly handle extra keys. Use `vol.Schema(..., extra=vol.ALLOW_EXTRA)` to permit them, or `vol.Schema(..., extra=vol.REMOVE_EXTRA)` to silently ignore them.

Generated OpenAPI schema does not include a specific OpenAPI feature (e.g., `oneOf`, `anyOf`, advanced validation rules) or is not fully compliant with OpenAPI 3.1.

`voluptuous-openapi` might not yet support all advanced features of the latest OpenAPI specifications, or the Voluptuous schema used might not be expressive enough to translate into the desired OpenAPI constructs.

fix

Consult the `voluptuous-openapi` GitHub repository and documentation for supported OpenAPI versions and features. For complex or custom validators, explore implementing a custom serializer as described in the library's README to extend its conversion capabilities.

Upgrade

Version history

0.3.0latest on PyPI · released Dec 31, 2025

Audit

Dependencies

voluptuousrequiredCore library for defining schemas that are converted to OpenAPI.

openapi-schema-validatorrequiredUsed for validating the generated OpenAPI Schema objects.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/home-assistant-libs/voluptuous-openapi ↗

packagehttps://pypi.org/project/voluptuous-openapi/ ↗