doc.go

// Package validator validates structs, maps, JSON documents, form values and
// single values against boolean rule expressions, and binds validated input
// into structs.
//
// # Inputs
//
// A Validator turns an input into a Validation. Struct reads rules from
// struct tags (validate:"..." by default); Map, JSON and Values take a
// field -> expression map; Value checks one value under the name "value".
// The package-level functions of the same names use a shared Validator with
// the built-in rules; construct your own with New when rules, messages or
// options differ. Constructors return input and rule errors immediately.
// Validate evaluates every field and collects failures; Valid reports only
// the verdict and stops at the first failure; ValidateAs validates and then
// binds the filtered input into a struct atomically.
//
// # Expressions
//
// An expression combines rules with !, && and ||, in that precedence order,
// and parentheses:
//
//	required && (email || regex:"^[a-z]+@example\\.com$")
//
// Arguments follow a colon and are separated by commas (between:3,20); double
// quotes and backslashes protect commas, operators and parentheses. "dive"
// splits a collection field's expression into rules for the collection and
// rules for each element: "required && min:1 && dive && alpha". "sometimes"
// on the top-level && chain skips the field when it is absent from the input,
// which suits PATCH requests.
//
// # Rules and filters
//
// Most built-in rules pass empty values so that presence is the job of
// required, filled and notblank; WithStrictRequired makes required reject
// zero values as well. Size rules compare numbers by value and strings by
// rune count, unless a numeric or number assertion in the same expression
// switches them to numeric comparison. Rules returns the built-in catalog;
// custom rules implement Rule, or FallibleRule when the check itself can
// fail, and are registered with options. Filters (trim, lower, int, ...)
// transform a value before its rules run and before ValidateAs binds it.
//
// # Errors
//
// Validate returns *Errors for field failures, with messages resolved through
// WithMessages, WithTranslation, WithAttributes and AddMessages; AsErrors
// recovers the collection from a wrapped error. A rule that cannot complete
// yields a *RuleError wrapping ErrRuleEvaluation and is never reported as a
// field failure. Invalid expressions yield *RulesError wrapping
// ErrInvalidRules from the constructors and from Check. Bind and ValidateAs
// are atomic and report *BindError wrapping ErrBindConversion.
//
// # Concurrency
//
// A Validator is immutable and safe for concurrent use, and its expression,
// plan and struct caches are bounded. A Validation is not safe for concurrent
// use. Rules and filters must be safe for concurrent use, because one
// Validator serves many goroutines, and Passes must be deterministic, because
// the engine may evaluate a rule more than once for one value.
package validator