#validate API reference

Declarative validation of a map of string to string (a form body, a query, a config) against a rule set, returning a structured error list instead of ad-hoc per-field if checks. Rules compose as value-semantic descriptors built by the validate.required / isInt / min / pattern / email / ... family; group them per field in a map of string to list of Rule and call validate.check. Pure Jennifer over regex + uri + time + password + convert + lists + strings + maps, so it runs on both binaries.

Values are strings (the shape web.bodyForm / dotenv / a query string produce): a type rule (isInt / isFloat / isBool) checks the string parses; min / max parse then compare; minLen / maxLen measure the string. A field that is absent or blank passes every rule except required - so an optional field left empty is valid. Only the fields named in the rule set are checked; extra data keys are ignored.

Import with import "validate.j" as validate;. See the validate guide for prose and examples.

#Functions

#validate.byField(errs as list of Failure)

Group error messages by field (for re-rendering a form with per-field errors).

Parameters

• errs {list of Failure} - the failures

Returns {map of string to list of string} - field -> its messages

#validate.check(data as map of string to string, rules as map of string to list of Rule)

Validate data against a rule set, returning every failure. Empty means valid.

Parameters

• data {map of string to string} - the field values
• rules {map of string to list of Rule} - rules per field

Returns {list of Failure} - the failures (empty when valid)

#validate.custom(fn as func, message as string)

A custom rule: fn is a func(value as string) returning true when valid.

Parameters

• fn {func} - the predicate
• message {string} - the message when the predicate fails

Returns {Rule} - the rule

#validate.datetime(format as string)

Require the value to be a valid date/time in the given strftime format (time's format codes): "%d.%m.%Y" for dd.mm.yyyy, "%m/%d/%Y" for mm/dd/yyyy, "%Y-%m-%d" for ISO, "%Y-%m-%d %H:%M" for a date-time. The value must both match the format and be a real calendar date (month 13 or day 32 fail), since it is checked with time.parse. Pair with withMessage for a user-facing "use DD.MM.YYYY" hint.

Parameters

• format {string} - the strftime format the value must match

Returns {Rule} - the rule

#validate.email()

Require the value to look like an email address.

Returns {Rule} - the rule

#validate.isBool()

Require the value to be exactly "true" or "false".

Returns {Rule} - the rule

#validate.isFloat()

Require the value to parse as a number (int or float).

Returns {Rule} - the rule

#validate.isInt()

Require the value to parse as an integer.

Returns {Rule} - the rule

#validate.localize(failures as list of Failure, templates as map of string to string)

Re-render failures with caller-supplied per-rule message templates - for non-English messages, or a house style. templates maps a rule id (the Failure.rule, e.g. "min" / "email") to a template string; %param% is replaced with the failure's param (a threshold, joined choices) and %field% with its field name. A rule not in templates keeps its default message, so a partial map overrides only the rules it names. The templates can come from anywhere - a literal map, a config, or intl.tr per rule id. Returns the failures with message replaced, so it composes with messages / byField. The markers are %name%-style (brace-free) on purpose: they never collide with the language's {expr} string interpolation, so a template reads the same in a cooked or raw string. Substitution is a single pass (a substituted value is never re-scanned), and a literal % is written %%.

Parameters

• failures {list of Failure} - the failures from check
• templates {map of string to string} - rule id -> message template

Returns {list of Failure} - the failures with localized messages

#validate.max(n as float)

Require the numeric value to be at most n.

Parameters

• n {float} - the maximum

Returns {Rule} - the rule

#validate.maxLen(n as int)

Require the string to be at most n characters (runes).

Parameters

• n {int} - the maximum length

Returns {Rule} - the rule

#validate.messages(errs as list of Failure)

Render an error list as "field: message" strings (for logging or a flash).

Parameters

• errs {list of Failure} - the failures

Returns {list of string} - one line per error

#validate.min(n as float)

Require the numeric value to be at least n.

Parameters

• n {float} - the minimum

Returns {Rule} - the rule

#validate.minLen(n as int)

Require the string to be at least n characters (runes).

Parameters

• n {int} - the minimum length

Returns {Rule} - the rule

#validate.noneOf(blocked as list of string)

Reject the value if it is one of blocked (a blacklist - reserved usernames, banned words). Exact, case-sensitive matching, like oneOf; for a case-insensitive blacklist use a pattern with the (?i) flag, or normalise the value first.

Parameters

• blocked {list of string} - the forbidden values

Returns {Rule} - the rule

#validate.ok(data as map of string to string, rules as map of string to list of Rule)

Whether data satisfies every rule (a short-circuit over check).

Parameters

• data {map of string to string} - the field values
• rules {map of string to list of Rule} - rules per field

Returns {bool} - true when valid

#validate.oneOf(allowed as list of string)

Require the value to be one of allowed.

Parameters

• allowed {list of string} - the permitted values

Returns {Rule} - the rule

#validate.password(policy as pw.Schema)

Require the value to satisfy a password policy - length bounds and per-class minimums - by delegating to the password module's validate. Build policy with password.schema() and its with* builders. On failure the message is the policy's own failed-rule reasons, joined; override with withMessage for a single user-facing hint. Like every rule but required, an absent or blank value is skipped - pair with required to also demand a value.

Parameters

• policy {pw.Schema} - the policy to enforce (a Schema from the password module)

Returns {Rule} - the rule

#validate.pattern(re as string)

Require the value to match an RE2 regular expression (anchored yourself with ^ / $ if you want a full match).

Parameters

• re {string} - the regex source

Returns {Rule} - the rule

#validate.required()

Require the field to be present and non-empty. Every other rule is skipped for an absent or blank field, so pair required with them to also validate a value.

Returns {Rule} - the rule

#validate.url()

Require the value to be an absolute URL (a scheme and a host).

Returns {Rule} - the rule

#validate.withMessage(r as Rule, message as string)

Override the message of an already-built rule (fluent).

Parameters

• r {Rule} - the rule
• message {string} - the message to use on failure

Returns {Rule} - the updated rule

#Structs

#validate.Failure

One validation failure. rule is a stable id (the rule kind) and param is the rule's argument in string form (a threshold, a joined choices list) - the two a caller needs to render a custom or localized message via localize. The built-in message is the default (English).

#validate.Rule

One validation rule (descriptor). Built by the rule family (required / isInt / min / ...); not usually constructed directly.