Built-ins by role

The API reference lists every name with its signature, and the voluptuous compatibility page maps each name to its status against voluptuous. This page is the third lens: what role each built-in plays, so you can find the right tool by the job you need done rather than by remembering its name.

Everything here splits into four roles:

• Markers are dictionary keys that carry intent (required, optional, secret).
• Combinators compose or wrap other validators (All, Any, Maybe).
• Validators check a value and return it unchanged.
• Transformers return a changed value.

The line that matters most runs between the last two. A validator is a gate: the value passes through untouched or it raises. A transformer rewrites the value, so the thing that comes out is not the thing that went in. Transformers split again by whether the type changes:

• A converter changes the type ("5" to 5, "192.0.2.1" to an IPv4Address). Its name says so: As<Type> converts to a named type, From<Source> decodes a source, Coerce is the generic one.
• A normalizer keeps the type and cleans the value ("ABC" to "abc", a number clamped into a range). Its name reads as an action on the value (Lower, Strip, Clamp).

Knowing the role tells you where a name belongs in a chain. Validators and transformers run left to right inside All, so a converter early in the chain decides the type every later step sees.

Markers

Dictionary keys that carry intent. Each compares and hashes by its underlying key, so a marker stands in for the bare key.

Name	Note
Required	The key must be present.
Optional	The key may be present; a default fills in.
Remove	Drop matching keys from the output.
Extra	Catch-all key for the rest of a mapping.
Inclusive	Group of keys that must appear together.
Exclusive	Group of keys of which at most one may appear.
Self	A recursive reference to the schema.
Forbidden	The key must be absent.
Alias	Accept the key under alternate input names.
Secret	Redact the key’s value in error output.

Combinators and wrappers

Compose or wrap other validators.

Name	Note
All	Run each in turn; the output of one feeds the next.
Any	The first that accepts wins.
And	Alias of All.
Or	Alias of Any.
Union	Any with an optional discriminant.
Switch	Alias of Union.
TaggedUnion	Route on one key’s value to the matching schema.
SomeOf	Between min_valid and max_valid must pass.
Maybe	Accept None, otherwise the wrapped validator.
Msg	Override a validator’s error message.

Validators

Check a value and return it unchanged.

Value and type

Name	Note
Literal	Equal to a literal value.
Equal	Equal to a target.
In	A member of a container.
NotIn	Not a member of a container.
Contains	Contains a target value.
Match	Matches a regular expression.
IsRegex	A compilable regular expression.
Object	Attributes validated like a mapping.
ExactSequence	A sequence matching a fixed shape.
Unordered	A sequence in any order.
Unique	No duplicate elements.
Sorted	Already in ascending order.
Length	Length within bounds.
NonEmpty	Not empty.

Numbers

Name	Note
Range	Within a numeric range.
Number	A number; yield_decimal=True returns a Decimal.
Positive	Greater than zero.
Negative	Less than zero.
NonNegative	Zero or greater.
MultipleOf	An exact multiple of a base.
Byte	An integer from 0 to 255.
SmallFloat	A float from 0 to 1.
Latitude	A valid latitude.
Longitude	A valid longitude.
Percentage	A number or "NN%" string in 0 to 100.

Strings and formats

Name	Note
Email	An email address.
Url	A URL.
FqdnUrl	A URL with a fully qualified domain.
Slug	A URL slug.
Alpha	Letters only.
Alphanumeric	Letters and digits only.
ASCII	ASCII characters only.
PrintableASCII	Printable ASCII only.
NoWhitespace	No whitespace characters.
StartsWith	Begins with a prefix.
EndsWith	Ends with a suffix.
ByteLength	UTF-8 byte length within bounds.
HexColor	A hex color; compose Lower/Upper for case.
Hex	Hexadecimal; checks, does not decode.
Base64	Base64; checks, does not decode.
JSONString	A JSON string; value via FromJSONString.
ULID	A ULID; compose Upper for canonical case.
DataURI	A data: URI.
Datetime	A datetime string; string in, string out.
Date	A date string; string in, string out.
Time	A time string; string in, string out.
Duration	A duration (also a timedelta, a number of seconds, or a mapping); object via AsTimedelta.
TimeZone	A UTC offset; object via AsTimezone.
TimeZoneInfo	An IANA name; object via Coerce(ZoneInfo).

Network and identifier

Check the format and return the string unchanged. The parsed object is opt-in through Coerce, since each of these types constructs from its string.

Name	Note
Hostname	A hostname.
Fqdn	A fully qualified domain name.
Port	A TCP/UDP port number; returns an int.
MacAddress	A MAC address; canonical form via NormalizeMacAddress.
UUID	A UUID; object via Coerce(uuid.UUID).
IPv4Address	Object via Coerce(ipaddress.IPv4Address).
IPv6Address	Object via Coerce(ipaddress.IPv6Address).
IPAddress	Object via Coerce(ipaddress.ip_address).
IPNetwork	Object via Coerce(lambda v: ipaddress.ip_network(v, strict=False)); plain ip_network rejects host bits.

Filesystem

Name	Note
IsDir	An existing directory.
IsFile	An existing file.
PathExists	An existing path.
IsSymlink	A symbolic link.
IsSocket	A socket.
IsFifo	A FIFO.
IsBlockDevice	A block device.

Truthiness

Name	Note
IsTrue	A truthy value.
IsFalse	A falsy value.

Cross-field and mapping rules

Run over a whole mapping, usually after a dict schema with All.

Name	Note
RequiredWith	Required when another key is present.
RequiredWithout	Required when another key is absent.
RequiredIf	Required when a condition holds.
Check	An arbitrary predicate over the value.
AtLeastOne	At least one of a set of keys is present.
AtMostOne	At most one of a set of keys is present.
ExactlyOne	Exactly one of a set of keys is present.
AllOrNone	All of a set of keys, or none.
Immutable	Rejects a change against the prior value.
WriteOnce	Rejects a second write.

Transformers

Return a changed value.

Converters

The type changes.

Name	Result
Coerce	type(value), the generic convert.
Boolean	A string to a bool.
Set	An iterable to a set.
EnsureList	A scalar to a one-element list.
AsDatetime	A string to a datetime.
AsDate	A string to a date.
AsTime	A string to a time.
AsTimedelta	A duration to a timedelta.
AsTimezone	An offset to a datetime.timezone.
FromEpoch	A timestamp to a datetime.
FromPercentage	"80%" to a float.
HexInt	A hex string to an int.
FromJSONString	A JSON string to the decoded value.
DefaultTo	None to a default (substitution).
EmptyToNone	An empty string or container to None.
Map	A value to its entry in a lookup table.
SetTo	Anything to a fixed value (substitution).

Normalizers

The type stays; the value is cleaned.

Name	Result
Lower	Lowercase.
Upper	Uppercase.
Capitalize	Capitalized.
Title	Title-cased.
Strip	Whitespace trimmed.
CollapseWhitespace	Whitespace runs squeezed to one space.
RemovePrefix	A leading prefix removed if present.
RemoveSuffix	A trailing suffix removed if present.
Truncate	Cut to at most max_length characters.
Replace	Regular-expression replace.
Clamp	A number pinned into a range.
NormalizeMacAddress	A MAC address in canonical form.
CreditCard	A card number (Luhn), stripped to bare digits.
IBAN	An IBAN (mod-97), compacted and upper-cased.
E164	An E.164 phone number, grouping stripped.

Arithmetic

Compute a new number from the input. The result follows Python’s own arithmetic type, so an integer operation on an int stays an int, while a divisor or a fractional operand yields a float (Divide and Remap always do).

Name	Result
Multiply	A number times a factor.
Divide	A number divided by a divisor.
Offset	A number plus an amount.
Round	A number rounded to decimals, or to an integer.
RoundUp	A number’s ceiling (a whole integer).
RoundDown	A number’s floor (a whole integer).
Snap	A number rounded to the nearest step.
Abs	A number’s absolute value.
Modulo	A number reduced modulo n (wrap-around).
Remap	A number mapped from one range onto another.
Scale	A number rescaled (factor/divisor/offset).

Collections

Reshape a list rather than validate it. Sort and Dedupe are the doing siblings of the Sorted and Unique validators.

Name	Result
Split	A delimited string into a list.
Join	A list into a delimited string.
Sort	A list ordered (a new list).
Dedupe	A list without duplicates, first-seen order kept.
First	The first item of a sequence.
Last	The last item of a sequence.
Without	A list without the listed values.

CreditCard, IBAN, and E164 normalize by default; pass normalize=False to validate and return the value unchanged.