Validators

All validators accept a value via their validate() method. On success they return the validated (possibly coerced) value. On failure they raise ValidationError.

StringValidator

class valify.validators.StringValidator(*, min_length: int | None = None, max_length: int | None = None, strip: bool = True)[source]

Bases: Validator

Validates that a value is a string, with optional length constraints.

Parameters:

min_length (int or None) – Minimum allowed length. None means no minimum.
max_length (int or None) – Maximum allowed length. None means no maximum.
strip (bool) – If True, strip leading/trailing whitespace before validating. Defaults to True.

Example

v = StringValidator(min_length=2, max_length=50) v.validate(“Alice”) # returns “Alice” v.validate(“A”) # raises ValidationError

to_json_schema() → dict[str, Any][source]

Returns a JSON Schema representation of this validator.

Returns:: JSON schema fragment describing the validator.
Return type:: dict

validate(value: Any) → str[source]

Parameters:: value (Any) – The value to validate.
Returns:: The validated (and possibly coerced) value.
Return type:: Any
Raises:: ValidationError – If the value fails validation.

IntValidator

class valify.validators.IntValidator(*, min_value: int | None = None, max_value: int | None = None, coerce: bool = False)[source]

Bases: Validator

Validates that a value is an integer, with optional range constraints.

Parameters:

min_value (int or None) – Minimum allowed value. None means no minimum.
max_value (int or None) – Maximum allowed value. None means no maximum.
coerce (bool) – If True, attempt to convert strings to int before validating. Defaults to False.

Example

v = IntValidator(min_value=0, max_value=120) v.validate(25) # returns 25 v.validate(-1) # raises ValidationError

to_json_schema() → dict[str, Any][source]

Returns a JSON Schema representation of this validator.

Returns:: JSON schema fragment describing the validator.
Return type:: dict

validate(value: Any) → int[source]

Parameters:: value (Any) – The value to validate.
Returns:: The validated (and possibly coerced) value.
Return type:: Any
Raises:: ValidationError – If the value fails validation.

FloatValidator

class valify.validators.FloatValidator(*, min_value: float | None = None, max_value: float | None = None, coerce: bool = False)[source]

Bases: Validator

Validates that a value is float, with optional range values.

Parameters:

min_value (float or None) – Minimum allowed value. None means no minimum.
max_value (float or None) – Maximum allowed value. None means no maximum.
coerce (bool) – If True, attempt to convert strings and ints to float. Defaults to False.

Example

v = FloatValidator(min_value=0.0, max_value=1.0) v.validate(0.5) # returns 0.5 v.validate(1.5) # raises ValidationError

to_json_schema() → dict[str, Any][source]

Returns a JSON Schema representation of this validator.

Returns:: JSON schema fragment describing the validator.
Return type:: dict

validate(value: Any) → float[source]

Parameters:: value (Any) – The value to validate.
Returns:: The validated (and possibly coerced) value.
Return type:: Any
Raises:: ValidationError – If the value fails validation.

BoolValidator

class valify.validators.BoolValidator(*, coerce: bool = False)[source]

Bases: Validator

Validates that a value is boolean.

Parameters:: coerce (bool) – If True, accept truthy strings like ‘true’, ‘false’, ‘1’, ‘0’. Defaults to False.

Example

v = BoolValidator() v.validate(True) # returns True v.validate(“true”) # raises ValidationError unless coerce=True

to_json_schema() → dict[str, Any][source]

Returns a JSON Schema representation of this validator.

Returns:: JSON schema fragment describing the validator.
Return type:: dict

validate(value: Any) → bool[source]

Parameters:: value (Any) – The value to validate.
Returns:: The validated (and possibly coerced) value.
Return type:: Any
Raises:: ValidationError – If the value fails validation.

EmailValidator

class valify.validators.EmailValidator[source]

Bases: Validator

Validates that a value is valid email address.

This validator checks format only — it does not send a confirmation email or verify the address exists. This is intentional: full email verification requires network access, which a validator should never do.

Example

v = EmailValidator() v.validate(”alice@example.com”) # returns “alice@example.com” v.validate(“not-an-email”) # raises ValidationError

to_json_schema() → dict[str, Any][source]

Returns a JSON Schema representation of this validator.

Returns:: JSON schema fragment describing the validator.
Return type:: dict

validate(value: Any) → str[source]

Parameters:: value (Any) – The value to validate.
Returns:: The validated (and possibly coerced) value.
Return type:: Any
Raises:: ValidationError – If the value fails validation.

OptionalValidator

class valify.validators.OptionalValidator(validator: Validator, *, default: Any = None)[source]

Bases: Validator

Wraps any validator and makes its field optional.

If the value is None or the field is missing, returns the default value instead of raising ValidationError.

Parameters:

validator (Validator) – The validator to apply if a value is present.
default (Any) – Value to return when the field is absent or None. Defaults to None.

Example

v = OptionalValidator(StringValidator(min_length=2), default=””) v.validate(“Alice”) # returns “Alice” v.validate(None) # returns “”

to_json_schema() → dict[str, Any][source]

Returns a JSON Schema representation of this validator.

Returns:: JSON schema fragment describing the validator.
Return type:: dict

validate(value: Any) → Any[source]

Parameters:: value (Any) – The value to validate.
Returns:: The validated (and possibly coerced) value.
Return type:: Any
Raises:: ValidationError – If the value fails validation.

ListValidator

class valify.validators.ListValidator(item_validator: Validator, *, min_items: int | None = None, max_items: int | None = None)[source]

Bases: Validator

Validates that a value is a list, with each item passing a validator.

Parameters:

item_validator (Validator) – The validator applied to every item in the list.
min_items (int or None) – Minimum number of items. None means no minimum.
max_items (int or None) – Maximum number of items. None means no maximum.

Example

v = ListValidator(StringValidator(), min_items=1, max_items=5) v.validate([“alice”, “bob”]) # returns [“alice”, “bob”] v.validate([]) # raises ValidationError

to_json_schema() → dict[str, Any][source]

Returns a JSON Schema representation of this validator.

Returns:: JSON schema fragment describing the validator.
Return type:: dict

validate(value: Any) → list[Any][source]

Parameters:: value (Any) – The value to validate.
Returns:: The validated (and possibly coerced) value.
Return type:: Any
Raises:: ValidationError – If the value fails validation.

EnumValidator

class valify.validators.EnumValidator(choices: list[Any] | set[Any], *, case_sensitive: bool = True)[source]

Bases: Validator

Validates that a value is one of a fixed set of allowed choices.

Parameters:

choices (list or set) – The collection of allowed values.
case_sensitive (bool) – If False, string comparisons are case-insensitive. Defaults to True.

Example

v = EnumValidator(choices=[“admin”, “user”, “guest”]) v.validate(“admin”) # returns “admin” v.validate(“root”) # raises ValidationError

to_json_schema() → dict[str, Any][source]

Returns a JSON Schema representation of this validator.

Returns:: JSON schema fragment describing the validator.
Return type:: dict

validate(value: Any) → Any[source]

Parameters:: value (Any) – The value to validate.
Returns:: The validated (and possibly coerced) value.
Return type:: Any
Raises:: ValidationError – If the value fails validation.

JSON Schema Export

All validators support exporting themselves to JSON Schema via to_json_schema().

Example:

from valify import StringValidator

validator = StringValidator(
    min_length=2,
    max_length=50,
)

print(validator.to_json_schema())

Output:

{
    "type": "string",
    "minLength": 2,
    "maxLength": 50
}

JSON Schema export enables integration with:

OpenAPI
FastAPI
Form generators
Documentation systems
Other JSON Schema compatible tools