Skip to content
Support this libraryStar on GitHub

Validation Library for Go ​

GoForj validation gopher with a checklist

Typed fluent validation with reusable rules and useful field errors.

Go ReferenceMIT LicenseCISecurityGo 1.24 or newerVersion v0.1.0Measured unit coverageExecuted Go tests

Keep field names, values, and constraints together. Validate decoded requests, configuration, and domain values using ordinary Go code, with no runtime dependencies.

FeatureWhat it provides
 Typed chainsTyped builders for text, numbers, exact decimals, time, and collections.
 Reusable rulesCompose rules and plug in custom validators without global registration.
 Format checksCommon formats and character checks directly in the fluent chain.
 Field errorsOrdered paths, stable codes, custom messages, and localization hooks.
 Optional inputsDistinguish omitted fields, explicit null, and supplied zero values.

Quick start ​

Requires Go 1.24 or newer.

sh
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:

go
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 or StopOnFirstError() 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 ​

GroupFunctions
ValuesString · Number · Bool · Validate
FormatsIsEmail · IsURL · IsUUID · IsUUIDv4 · IsUUIDv7 · IsIP · IsIPv4 · IsIPv6 · IsJSON · IsBase64
ConditionsWhen
CollectionsGroup · Slice · Each
Custom rulesUsing · Invalid
ContextValidateContext · Check
Domain valuesValue · RuleFunc · ContextRuleFunc
ErrorsLabel · Message · First · Messages · Issues
ConstraintsRequired · RequiredIf · NotBlank · Min · Max · In · Equal · Match · Accepted
Text constraintsLen · Contains · NotContains · StartsWith · EndsWith · NotEqual · NotIn
Numeric constraintsGreaterThan · LessThan · MultipleOf
Collection constraintsMap · Unique · UniqueBy · HasKey · OnlyKeys
Dates and timesTime · Before · After · IsDate · IsDateIn
Optional inputsPresence · Nullable · Optional · Provided · Null · IsPresent · IsNull · Get
More formatsIsULID · IsHostname · IsCIDR · IsMAC · IsE164 · IsBase64URL · IsAlpha · IsAlphanumeric · IsDigits · IsASCII · IsLowercase · IsUppercase · IsUTF8
CompositionAny · All · Not
Evaluation policyNew · CollectAll · StopOnFirstError · FormatMessages
Exact decimalsDecimal · MaxScale

Values ​

String · Number · Bool · Validate ​

String starts a deferred chain for a borrowed application value.

go
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.

go
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.

go
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.

go
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 min

Custom rules ​

Using · Invalid ​

Using attaches a reusable validator for the exact value type.

go
// 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.

go
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))
// true

Domain values ​

Value · RuleFunc · ContextRuleFunc ​

Value starts a deferred chain for a borrowed application value.

go
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.

go
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.

go
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.

go
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.

go
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.

go
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.

go
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.

go
// 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.

go
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.

go
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.

go
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: required

Exact 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.

go
// 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 ​

sh
make test
make test-race
make vet
make test-coverage
make generate
make check-generated

The 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.