{"id":8764,"library":"voluptuous-openapi","title":"Voluptuous OpenAPI Converter","description":"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.","status":"active","version":"0.3.0","language":"en","source_language":"en","source_url":"https://github.com/home-assistant-libs/voluptuous-openapi","tags":["openapi","voluptuous","schema validation","api documentation","data validation","converter"],"install":[{"cmd":"pip install voluptuous-openapi==0.3.0","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core library for defining schemas that are converted to OpenAPI.","package":"voluptuous","optional":false},{"reason":"Used for validating the generated OpenAPI Schema objects.","package":"openapi-schema-validator","optional":false}],"imports":[{"note":"The primary function to convert Voluptuous schemas.","symbol":"convert","correct":"from voluptuous_openapi import convert"},{"note":"Common alias for the underlying voluptuous library for schema definition.","symbol":"vol","correct":"import voluptuous as vol"}],"quickstart":{"code":"import voluptuous as vol\nfrom voluptuous_openapi import convert\n\n# Define a simple Voluptuous schema\nschema = vol.Schema({\n    vol.Required('name'): vol.All(str, vol.Length(min=5)),\n    vol.Optional('age'): vol.All(int, vol.Range(min=0)),\n    'email': vol.Email,\n})\n\n# Convert the Voluptuous schema to an OpenAPI Schema object\nopenapi_schema = convert(schema)\n\n# Print the resulting OpenAPI schema (dictionary representation)\nimport json\nprint(json.dumps(openapi_schema, indent=2))","lang":"python","description":"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`."},"warnings":[{"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.","message":"OpenAPI 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.","severity":"breaking","affected_versions":"OpenAPI Spec versions 3.0 vs 3.1"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"OpenAPI 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.","severity":"gotcha","affected_versions":"OpenAPI Spec version 3.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install voluptuous-openapi` to install the package.","cause":"The 'voluptuous-openapi' library has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'voluptuous_openapi'"},{"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.","cause":"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.","error":"voluptuous.error.Invalid: extra keys not allowed @ data['unexpected_key']"},{"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.","cause":"`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.","error":"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."}]}