Validation Library for Go

Typed fluent validation with reusable rules and useful field errors.
Keep field names, values, and constraints together. Validate decoded requests, configuration, and domain values using ordinary Go code, with no runtime dependencies.
| Feature | What it provides |
|---|---|
| Typed builders for text, numbers, exact decimals, time, and collections. | |
| Compose rules and plug in custom validators without global registration. | |
| Common formats and character checks directly in the fluent chain. | |
| Ordered paths, stable codes, custom messages, and localization hooks. | |
| Distinguish omitted fields, explicit null, and supplied zero values. |
Quick start
Requires Go 1.24 or newer.
go get github.com/goforj/[email protected]For the unreleased exact-decimal API, use go get github.com/goforj/validation@main.
The complete registration program defines the Registration model and imports the library:
req := Registration{
Name: "Ada",
Email: "[email protected]",
Age: 36,
Terms: true,
}
err := validation.Validate(
validation.String("name", req.Name).Required().Min(2).Max(100),
validation.String("email", req.Email).Required().IsEmail(),
validation.Number("age", req.Age).Min(18),
validation.Bool("terms", req.Terms).Accepted(),
)
fmt.Println(err)
// <nil>How it works
- Values are explicit. Zero and false are ordinary values. Rules evaluate empty strings unless you use a lazy condition to omit a field. Required checks run before content checks.
- Errors stay useful. Validation collects the first violation per field by default. Use
New().CollectAll()for all content failures orStopOnFirstError()to stop globally. Custom messages retain their machine code. Unexpected rule errors abort evaluation and remain operational errors. - Custom rules fit the same chain. Implement Rule[T] with Validate(T) error, or use a function adapter. Return validation.Invalid for an input failure. Add RuleWithContext[T] for dependencies that need cancellation.
- Evaluation is local. Builders can be branched and reused. Input slices and application dependencies are borrowed. Coordinate concurrent mutation in your application.
See validation contracts for presence, formats, paths, configuration errors, ownership, and cancellation.
Runnable examples
Run from the repository root with go run ./examples/<name>. Tests verify every program's output.
quickstart · formats · patch · nested · custom · context · domain · errors · constraints · advanced · time · presence · moreformats · policies · decimal
API index
Values
String · Number · Bool · Validate
String starts a deferred chain for a borrowed application value.
req := Registration{
Name: "Ada",
Email: "[email protected]",
Age: 36,
Terms: true,
}
err := validation.Validate(
validation.String("name", req.Name).Required().Min(2).Max(100),
validation.String("email", req.Email).Required().IsEmail(),
validation.Number("age", req.Age).Min(18),
validation.Bool("terms", req.Terms).Accepted(),
)
fmt.Println(err)
// <nil>Formats
IsEmail · IsURL · IsUUID · IsUUIDv4 · IsUUIDv7 · IsIP · IsIPv4 · IsIPv6 · IsJSON · IsBase64
IsEmail requires a bare ASCII mailbox with a dotted domain.
err := validation.Validate(
validation.String("email", "[email protected]").IsEmail(),
validation.String("site", "https://goforj.dev").IsURL(),
validation.String("id", "550e8400-e29b-41d4-a716-446655440000").IsUUID(),
validation.String("trace_id", "550e8400-e29b-41d4-a716-446655440000").IsUUIDv4(),
validation.String("request_id", "0190bde7-5ad0-7000-8000-000000000001").IsUUIDv7(),
validation.String("host", "::1").IsIP(),
validation.String("ip", "192.0.2.1").IsIPv4(),
validation.String("ipv6", "2001:db8::1").IsIPv6(),
validation.String("metadata", `{"source":"web"}`).IsJSON(),
validation.String("cursor", "YWJj").IsBase64(),
)
fmt.Println(err)
// <nil>Conditions
When
When evaluates the callback lazily only when condition is true.
return validation.Validate(
validation.When(req.Email != nil, func() validation.Field {
return validation.String("email", *req.Email).Required().IsEmail()
}),
)Collections
Group · Slice · Each
Group prefixes child paths with a literal parent label.
items := []Item{
{SKU: "book", Quantity: 0},
}
err := validation.Validate(
validation.Group("address", validation.String("city", "").Required()),
validation.Slice("items", items).Required().Max(100).
Each(func(item Item) []validation.Field {
return []validation.Field{
validation.String("sku", item.SKU).Required(),
validation.Number("quantity", item.Quantity).Min(1),
}
}),
)
failures := err.(*validation.Errors)
for _, issue := range failures.Issues() {
fmt.Println(issue.Path, issue.Code)
}
// address.city required
// items.0.quantity minCustom rules
Using · Invalid
Using attaches a reusable validator for the exact value type.
// AllowedDomain restricts registrations to a configured company domain.
type AllowedDomain struct {
Domain string
}
// Validate returns a safe input failure for addresses outside the company.
func (r AllowedDomain) Validate(value string) error {
_, domain, ok := strings.Cut(value, "@")
if !ok || !strings.EqualFold(domain, r.Domain) {
return validation.Invalid("email_domain", "Use your company email address.")
}
return nil
}
err := validation.Validate(
validation.String("email", "[email protected]").Required().IsEmail().
Using(AllowedDomain{Domain: "goforj.dev"}),
)
fmt.Println(err)
// Use your company email address.Context
ValidateContext · Check
ValidateContext evaluates with request cancellation and the configured collection policy.
unavailable := errors.New("directory unavailable")
err := validation.ValidateContext(context.Background(),
validation.String("email", "[email protected]").IsEmail().
Check(func(ctx context.Context, email string) error {
// A real directory client would use ctx and email here.
return unavailable
}),
)
fmt.Println(errors.Is(err, unavailable))
// trueDomain values
Value · RuleFunc · ContextRuleFunc
Value starts a deferred chain for a borrowed application value.
window := validation.RuleFunc[Delivery](func(value Delivery) error {
if value.Days > 30 {
return validation.Invalid("delivery_window", "Choose delivery within 30 days.")
}
return nil
})
available := validation.ContextRuleFunc[Delivery](func(ctx context.Context, value Delivery) error {
return ctx.Err()
})
err := validation.Validate(
validation.Value("delivery", Delivery{Days: 7}).Using(window).Using(available),
)
fmt.Println(err)
// <nil>Errors
Label · Message · First · Messages · Issues
Label sets the human-readable field name without changing its output path.
err := validation.Validate(
validation.String("email", "bad").Label("email address").IsEmail().
Message("Enter your work email address."),
)
var failures *validation.Errors
if errors.As(err, &failures) {
fmt.Println(failures.First("email"))
// Enter your work email address.
fmt.Println(failures.Messages()["email"])
// [Enter your work email address.]
fmt.Println(failures.Issues()[0].Code)
// email
}Constraints
Required · RequiredIf · NotBlank · Min · Max · In · Equal · Match · Accepted
Required rejects an empty string before content rules run.
err := validation.Validate(
validation.String("name", "Ada").Required().NotBlank().Min(2).Max(100),
validation.String("company", "").RequiredIf(false).Max(200),
validation.String("role", "member").In("member", "admin"),
validation.String("confirmation", "correct horse").Equal("correct horse"),
validation.String("sku", "BOOK-42").Match(regexp.MustCompile(`^[A-Z]+-\d+$`)),
validation.Number("age", 36).Min(18).Max(120),
validation.Bool("terms", true).Accepted(),
)
fmt.Println(err)
// <nil>Text constraints
Len · Contains · NotContains · StartsWith · EndsWith · NotEqual · NotIn
Len requires exactly length Unicode code points.
err := validation.Validate(
validation.String("sku", "BOOK-42").Len(7).Contains("-").NotContains(" ").StartsWith("BOOK").EndsWith("42"),
validation.String("username", "ada").NotEqual("root").NotIn("admin", "system"),
)
fmt.Println(err)
// <nil>Numeric constraints
GreaterThan · LessThan · MultipleOf
GreaterThan requires a strict lower bound in the field's numeric type.
err = validation.Validate(
validation.Number("quantity", 12).GreaterThan(0).LessThan(100).MultipleOf(3),
)
fmt.Println(err)
// <nil>Collection constraints
Map · Unique · UniqueBy · HasKey · OnlyKeys
Map starts a deferred chain for a borrowed string-keyed map.
err = validation.Validate(
validation.Slice("tags", []string{"go", "books"}).Unique().Contains("go"),
validation.Slice("products", []Product{{ID: 1}, {ID: 2}}).
Using(validation.UniqueBy(func(product Product) int { return product.ID })),
validation.Map("labels", map[string]string{"category": "books"}).
Required().HasKey("category").OnlyKeys("category").
Each(func(key, value string) []validation.Field {
return []validation.Field{validation.String("", value).NotBlank()}
}),
)
fmt.Println(err)
// <nil>Dates and times
Time · Before · After · IsDate · IsDateIn
Time starts a deferred chain using instant comparisons across time zones.
starts := time.Date(2026, 11, 10, 10, 0, 0, 0, time.UTC)
ends := starts.Add(2 * time.Hour)
fmt.Println(validation.Validate(
validation.Time("starts_at", starts).Required().Before(ends).Min(starts).Max(ends).Equal(starts),
validation.Time("ends_at", ends).After(starts),
validation.String("date", "2026-11-10").IsDate(time.DateOnly),
validation.String("local_time", "2026-11-10 10:00").IsDateIn("2006-01-02 15:04", time.UTC),
))
// <nil>Optional inputs
Presence · Nullable · Optional · Provided · Null · IsPresent · IsNull · Get
Presence defers child validation until input contains a non-null value. Use an empty child path to retain path, or a named child to append a segment.
// nonBlank shares a content rule across optional and presence-aware inputs.
func nonBlank(value string) validation.Field { return validation.String("", value).NotBlank() }
var patch struct {
Seats validation.Input[int] `json:"seats,omitzero"`
Name validation.Input[string] `json:"name,omitzero"`
}
fmt.Println(json.Unmarshal([]byte(`{"seats":0,"name":null}`), &patch))
// <nil>
fmt.Println(validation.Validate(
validation.Presence("seats", patch.Seats, func(v int) validation.Field {
return validation.Number("", v).Min(0)
}).Required(),
validation.Presence("name", patch.Name, nonBlank).Nullable(),
))
// <nil>
fmt.Println(patch.Seats.IsPresent(), patch.Name.IsNull())
// true true
value, ok := validation.Provided(false).Get()
fmt.Println(value, ok, validation.Null[string]().IsNull())
// false true true
var nickname *string
fmt.Println(validation.Validate(validation.Optional(nickname, nonBlank)))
// <nil>
name := "Ada"
fmt.Println(validation.Validate(
validation.Optional(&name, nonBlank),
validation.Presence("name", validation.Provided(name), nonBlank),
))
// <nil>More formats
IsULID · IsHostname · IsCIDR · IsMAC · IsE164 · IsBase64URL · IsAlpha · IsAlphanumeric · IsDigits · IsASCII · IsLowercase · IsUppercase · IsUTF8
IsULID requires a case-insensitive 128-bit ULID.
fmt.Println(validation.Validate(
validation.String("id", "01ARZ3NDEKTSV4RRFFQ69G5FAV").IsULID(),
validation.String("host", "api.example.com").IsHostname(),
validation.String("network", "192.0.2.0/24").IsCIDR(),
validation.String("device", "00:11:22:33:44:55").IsMAC(),
validation.String("phone", "+14155552671").IsE164(),
validation.String("token", "__8").IsBase64URL(),
validation.String("name", "Ada").IsAlpha(),
validation.String("sku", "A123").IsAlphanumeric(),
validation.String("pin", "012345").IsDigits(),
validation.String("key", "header_name").IsASCII(),
validation.String("slug", "café").IsLowercase(),
validation.String("code", "ÉCOLE").IsUppercase(),
validation.String("title", "こんにちは").IsUTF8(),
))
// <nil>Composition
Any · All · Not
Any accepts a value when a rule succeeds; operational errors abort evaluation.
startsA := validation.RuleFunc[string](func(v string) error {
if strings.HasPrefix(v, "A") {
return nil
}
return validation.Invalid("starts_a", "Must start with A")
})
endsZ := validation.ContextRuleFunc[string](func(_ context.Context, v string) error {
if strings.HasSuffix(v, "Z") {
return nil
}
return validation.Invalid("ends_z", "Must end with Z")
})
fmt.Println(validation.Validate(
validation.String("code", "ABC").Using(validation.All(
validation.Any[string](startsA, endsZ),
validation.Not[string](endsZ),
)),
))
// <nil>
fmt.Println(validation.Validate(
validation.String("code", "XYZ").Using(validation.Any[string](startsA, endsZ)),
))
// <nil>Evaluation policy
New · CollectAll · StopOnFirstError · FormatMessages
New creates a validator with first-violation-per-field collection and default messages.
validator := validation.New().CollectAll().FormatMessages(func(issue validation.Issue) string {
return issue.Path + ": " + issue.Code
})
var failures *validation.Errors
if err := validator.Validate(
validation.String("name", "a").Min(3).Contains("z"),
); errors.As(err, &failures) {
fmt.Println(failures.Messages()["name"])
// [name: min name: contains]
}
first := validator.StopOnFirstError()
fmt.Println(first.ValidateContext(
context.Background(),
validation.String("name", "").Required(),
validation.Number("age", 0).Min(18),
))
// name: requiredExact decimals
Decimal · MaxScale
Decimal starts a deferred chain for signed decimal text without exponent notation. Values require ASCII integer digits and may include a fractional part with digits after the point.
// Currency is the application's currency-code type; validation maintains no currency registry.
type Currency string
const (
// USD is an application-supported currency code.
USD Currency = "USD"
// EUR is an application-supported currency code.
EUR Currency = "EUR"
)
// Invoice preserves decimal text and a typed currency code after application decoding.
type Invoice struct {
Amount json.Number
Currency Currency
}
invoice := Invoice{Amount: json.Number("1234.50"), Currency: USD}
fmt.Println(validation.Validate(
validation.Decimal("amount", invoice.Amount).
Required().Min("0.01").Max("999999.99").MaxScale(2),
validation.String("currency", invoice.Currency).In(USD, EUR),
))
// <nil>
fmt.Println(validation.Validate(
validation.Decimal("amount", "9007199254740993.01").
GreaterThan("9007199254740993").LessThan("9007199254740994").
Equal("9007199254740993.010"),
))
// <nil>Development
make test
make test-race
make vet
make test-coverage
make generate
make check-generatedThe root module contains the library and executable examples. The separate docs module contains documentation tooling. See development for checks and validation contracts for API behavior.
The initial release review records the review passes, fixes, and verification evidence.