validation

type Constraint ¶

type Constraint[T any] func(path string, value T) ReportValue

Constraint reports what is wrong with value, at the path by which value was reached. A value it accepts yields a nil ReportValue — the acceptance path therefore allocates nothing, which matters because it is the path taken on every field of every valid request.

path is the position of value inside the structure being validated, in the grammar JoinField / JoinIndex define; RootPath means "the value itself". A Constraint MUST propagate that path into every ViolationValue it reports, and MUST NOT invent a different grammar — the path is the whole reason a violation is actionable on a nested structure.

Implementations MUST be pure and safe for concurrent use: the same value at the same path always yields the same report, and one compiled Constraint is shared by every goroutine validating that type.

A Constraint MUST NOT copy the VALUE it rejected into the report. It names the rule and the bound; the value may be a password, a token or a national identifier, and a validation message is the one error message in a service that is designed to reach the end user. See ViolationValue.

type ReportValue ¶

type ReportValue []ViolationValue

ReportValue is every violation one validation found, in the order the constraints reported them. It is a SLICE rather than a struct so that the zero value — nil — is a passing report: a validator with no constraint passes, which is ADR 0046's first invariant and ADR 0031's "an empty configuration is not the same thing as a broken one".

Composition is therefore plain append, and the accepting path allocates nothing at all.

ReportValue is a published concrete shape (pkg/v1/validation.Report aliases it), so ADR 0040 applies: it may still change while the module is v0, said out loud, and not after v1.

func (r ReportValue) Err() error

func (r ReportValue) First() (violation ViolationValue, ok bool)

func (r ReportValue) OK() bool

func (r ReportValue) Paths() []string

type ViolationValue ¶

type ViolationValue struct {
	// Path locates the offending value inside the structure that was
	// validated, in the grammar of [JoinField] / [JoinIndex] —
	// "user.addresses[2].zip". [RootPath] (the empty string) means the value
	// as a whole, which is what a cross-field rule reports when no single
	// field is at fault.
	Path string
	// Rule names the constraint that refused, in lower case —
	// "required", "between", "length", "one_of", "pattern". It is the stable
	// identifier a caller switches on when the Code granularity is too coarse,
	// and the key an application uses to look up its own translated message.
	Rule string
	// Message explains the rule in one wire-safe line: no newline, no private
	// data, and — the part that is a security property rather than a style
	// choice — NEVER the rejected value itself. A validation message is the
	// one error message in a service designed to reach the end user, so a
	// message that echoed the value would exfiltrate whatever the caller was
	// unwise enough to validate: a password, a token, a card number. It names
	// the rule and the bound instead ("must be between 8 and 64 characters").
	Message string
	// Code is the dotted-quad identity of the rule that refused, so a caller
	// routes on it with errs.HasCode / errs.NewPrefixMatcher instead of
	// string-matching Rule. The built-in constraints own 0.3.47.*; a
	// consumer-written Constraint SHOULD carry a Code in the third-party
	// Major range (ADR 0019, 0x40-0x7F).
	Code errs.Code
}

ViolationValue is one located failure: WHERE it happened, WHICH rule it broke, a wire-safe explanation, and a routable errs.Code.

It is deliberately NOT an error. A validation normally produces several of them, and errors.Join of five would render five bracket headers, lose the ordering and bury the paths — while a single error would have to pick one violation to be about. The aggregate that IS convertible to an error is ReportValue; see its Err method.

The zero value is not meaningful; constraints build one per failure.