Voluptuous Serialize

2.7.0 · active · verified Tue Apr 14

Voluptuous Serialize is a Python library designed to convert `voluptuous` schemas into dictionaries, making them easily serializable (e.g., to JSON). It is built upon the `voluptuous` data validation library, extending its utility by providing a structured representation of schemas. The current version is 2.7.0, and it appears to have an active release cadence, with the latest version released in August 2025.

Warnings

deprecated The use of `"optional": true` within schema definitions is deprecated. Users should instead rely on the `"required"` key to indicate optional fields (i.e., `"required": false`).
Fix: Replace `vol.Optional('key', optional=True)` or schema outputs containing `"optional": true` with `vol.Optional('key')` which results in `"required": false` in the serialized output.
gotcha The library's GitHub README explicitly states it's for 'internal use of HA only' (Home Assistant). While usable by others, this suggests development priorities may align specifically with Home Assistant's needs, potentially leading to design choices or breaking changes that prioritize HA compatibility over general-purpose use cases.
Fix: Be aware that external use might require monitoring updates closely for HA-specific changes. Consider if your use case aligns with the implicit design goals of a library primarily maintained for another project.
gotcha The upstream `voluptuous` library, which `voluptuous-serialize` depends on, is in 'CONTRIBUTIONS ONLY' mode, as stated on its GitHub page. This implies that the original author is no longer actively fixing issues or adding features, relying solely on community pull requests. This could impact the long-term stability and responsiveness to bugs in the underlying validation logic.
Fix: Users should be aware of the upstream maintenance status. Report issues to both `voluptuous-serialize` and, if applicable, directly to the `voluptuous` project, and consider contributing fixes if critical issues arise.

Install

pip install voluptuous-serialize Install with pip

Imports

convert
```
from voluptuous_serialize import convert
```
The main function to serialize a voluptuous schema.
vol
```
import voluptuous as vol
```
Standard import alias for creating voluptuous schemas.

Quickstart

This quickstart demonstrates how to define a `voluptuous` schema and then use `voluptuous-serialize.convert` to transform it into a dictionary representation. The output is a list of dictionaries, each describing a field in the schema, including its name, type, and validation rules.

import voluptuous as vol
from voluptuous_serialize import convert

schema = vol.Schema({
    vol.Required("name"): vol.All(str, vol.Length(min=5)),
    vol.Required("age"): vol.All(vol.Coerce(int), vol.Range(min=18)),
    vol.Optional("email", default=""): str,
    vol.Optional("tags", default=[]): [str]
})

serialized_schema = convert(schema)
print(serialized_schema)

# Example of output structure (simplified):
# [
#     {'name': 'name', 'type': 'string', 'lengthMin': 5, 'required': True},
#     {'name': 'age', 'type': 'integer', 'valueMin': 18, 'required': True},
#     {'name': 'email', 'type': 'string', 'default': '', 'required': False},
#     {'name': 'tags', 'type': 'array', 'items': {'type': 'string'}, 'default': [], 'required': False}
# ]

view raw JSON →