Powerful struct field validation via tags plus extra validation utilities.
CI / CD
|
|
Quality
|
|
Security
|
|
Community
|
|
🚀 Installation
|
🧪 Examples & Tests
|
📚 Documentation
|
🤝 Contributing
|
🛠️ Code Standards
|
⚡ Benchmarks
|
🤖 AI Usage
|
⚖️ License
|
👥 Maintainers
|
go-validate requires a supported release of Go.
go get github.com/mrz1836/go-validateView the generated documentation
Heads up!
go-validateis intentionally light on dependencies. The only external package it uses is the excellenttestifysuite—and that's just for our tests. You can drop this library into your projects without dragging along extra baggage.
Development Setup (Getting Started)
Install MAGE-X build tool for development:
# Install MAGE-X for development and building
go install github.com/mrz1836/mage-x/cmd/magex@latest
magex update:installLibrary Deployment
This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:
brew install goreleaserThe release process is defined in the .goreleaser.yml configuration file.
Then create and push a new Git tag using:
magex version:bump bump=patch push=true branch=masterThis process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.
Build Commands
View all build commands
magex helpGitHub Workflows
All workflows are driven by modular configuration in .github/env/ — no YAML editing required.
Updating Dependencies
To update all dependencies (Go modules, linters, and related tools), run:
magex deps:updateThis command ensures all dependencies are brought up to date in a single step, including Go modules and any managed tools. It is the recommended way to keep your development environment and CI in sync with the latest versions.
All unit tests and fuzz tests run via GitHub Actions and use Go version 1.18.x. View the configuration file.
Run all tests (fast):
magex testRun all tests with race detector (slower):
magex test:raceBasic Struct Validation
package main
import (
"fmt"
"log"
"github.com/mrz1836/go-validate"
)
type User struct {
Name string `validation:"min_length=2 max_length=50"`
Email string `validation:"format=email"`
Age uint `validation:"min=18 max=120"`
Username string `validation:"min_length=3 max_length=20"`
}
func main() {
// Initialize validations (required)
validate.InitValidations()
user := User{
Name: "John Doe",
Email: "john@example.com",
Age: 25,
Username: "johndoe",
}
// Validate the struct
isValid, errors := validate.IsValid(user)
if !isValid {
for _, err := range errors {
fmt.Printf("Validation error: %s\n", err.Error())
}
} else {
fmt.Println("User is valid!")
}
}Password Confirmation Example
package main
import (
"fmt"
"github.com/mrz1836/go-validate"
)
type RegistrationForm struct {
Email string `validation:"format=email"`
Password string `validation:"min_length=8"`
PasswordConfirmation string `validation:"compare=Password"`
TermsAccepted bool // No validation needed
}
func main() {
validate.InitValidations()
form := RegistrationForm{
Email: "user@domain.com",
Password: "SecurePass123",
PasswordConfirmation: "SecurePass123", // Must match Password field
TermsAccepted: true,
}
isValid, errors := validate.IsValid(form)
if !isValid {
fmt.Println("Registration form has errors:")
for _, err := range errors {
fmt.Printf("- %s\n", err.Error())
}
} else {
fmt.Println("Registration form is valid!")
}
}Custom Regex Validation
package main
import (
"fmt"
"github.com/mrz1836/go-validate"
)
type Product struct {
SKU string `validation:"format=regexp:^[A-Z]{2,3}[0-9]{4,6}$"`
Name string `validation:"min_length=1 max_length=100"`
Price float64 `validation:"min=0.01"`
Description string `validation:"max_length=500"`
}
func main() {
validate.InitValidations()
product := Product{
SKU: "AB12345", // Must match pattern: 2-3 uppercase letters + 4-6 digits
Name: "Wireless Headphones",
Price: 99.99,
Description: "High-quality wireless headphones with noise cancellation",
}
isValid, errors := validate.IsValid(product)
if !isValid {
fmt.Println("Product validation failed:")
for _, err := range errors {
fmt.Printf("- %s\n", err.Error())
}
} else {
fmt.Println("Product is valid!")
}
}Using Extra Validation Functions
package main
import (
"fmt"
"github.com/mrz1836/go-validate"
)
type Contact struct {
Name string
Email string
Phone string
Website string
CountryCode string
}
func (c *Contact) Validate() (bool, []validate.ValidationError) {
var errors []validate.ValidationError
// Email validation with MX record check
if valid, err := validate.IsValidEmail(c.Email, true); !valid {
errors = append(errors, validate.ValidationError{
Key: "Email",
Message: err.Error(),
})
}
// Phone number validation (US/Canada/Mexico)
if valid, err := validate.IsValidPhoneNumber(c.Phone, c.CountryCode); !valid {
errors = append(errors, validate.ValidationError{
Key: "Phone",
Message: err.Error(),
})
}
// Website host validation
if c.Website != "" && !validate.IsValidHost(c.Website) {
errors = append(errors, validate.ValidationError{
Key: "Website",
Message: "is not a valid host or IP address",
})
}
return len(errors) == 0, errors
}
func main() {
contact := Contact{
Name: "Jane Smith",
Email: "jane@protonmail.com",
Phone: "555-123-4567",
Website: "janesmith.dev",
CountryCode: "1", // USA/Canada
}
isValid, errors := contact.Validate()
if !isValid {
fmt.Println("Contact validation failed:")
for _, err := range errors {
fmt.Printf("- %s\n", err.Error())
}
} else {
fmt.Println("Contact is valid!")
}
}Custom Validation Implementation
package main
import (
"fmt"
"reflect"
"strings"
"github.com/mrz1836/go-validate"
)
// Custom validation for allowed colors
type colorValidation struct {
validate.Validation
allowedColors []string
}
func (c *colorValidation) Validate(value interface{}, _ reflect.Value) *validate.ValidationError {
strValue, ok := value.(string)
if !ok {
return &validate.ValidationError{
Key: c.FieldName(),
Message: "must be a string",
}
}
// Check if color is in allowed list
for _, color := range c.allowedColors {
if strings.EqualFold(strValue, color) {
return nil // Valid
}
}
return &validate.ValidationError{
Key: c.FieldName(),
Message: fmt.Sprintf("must be one of: %s", strings.Join(c.allowedColors, ", ")),
}
}
// Builder function for the custom validation
func colorValidationBuilder(colors string, _ reflect.Kind) (validate.Interface, error) {
allowedColors := strings.Split(colors, ",")
for i, color := range allowedColors {
allowedColors[i] = strings.TrimSpace(color)
}
return &colorValidation{
allowedColors: allowedColors,
}, nil
}
type Car struct {
Make string `validation:"min_length=1"`
Model string `validation:"min_length=1"`
Year int `validation:"min=1900 max=2024"`
Color string `validation:"color=red,blue,green,black,white,silver"`
}
func main() {
// Register our custom validation
validate.AddValidation("color", colorValidationBuilder)
validate.InitValidations()
car := Car{
Make: "Toyota",
Model: "Camry",
Year: 2023,
Color: "blue", // Must be one of the allowed colors
}
isValid, errors := validate.IsValid(car)
if !isValid {
fmt.Println("Car validation failed:")
for _, err := range errors {
fmt.Printf("- %s\n", err.Error())
}
} else {
fmt.Println("Car is valid!")
}
}Enum Validation Example
package main
import (
"fmt"
"github.com/mrz1836/go-validate"
)
type OrderStatus string
const (
StatusPending OrderStatus = "pending"
StatusShipped OrderStatus = "shipped"
StatusDelivered OrderStatus = "delivered"
StatusCancelled OrderStatus = "cancelled"
)
type Order struct {
ID string
Status string
Priority string
}
func (o *Order) Validate() (bool, []validate.ValidationError) {
var errors []validate.ValidationError
// Validate order status using enum validation
allowedStatuses := []string{"pending", "shipped", "delivered", "cancelled"}
if valid, err := validate.IsValidEnum(o.Status, &allowedStatuses, false); !valid {
errors = append(errors, validate.ValidationError{
Key: "Status",
Message: err.Error(),
})
}
// Validate priority with empty allowed
allowedPriorities := []string{"low", "medium", "high", "urgent"}
if valid, err := validate.IsValidEnum(o.Priority, &allowedPriorities, true); !valid {
errors = append(errors, validate.ValidationError{
Key: "Priority",
Message: err.Error(),
})
}
return len(errors) == 0, errors
}
func main() {
order := Order{
ID: "ORD-12345",
Status: "shipped", // Valid status
Priority: "", // Empty allowed for priority
}
isValid, errors := order.Validate()
if !isValid {
fmt.Println("Order validation failed:")
for _, err := range errors {
fmt.Printf("- %s\n", err.Error())
}
} else {
fmt.Println("Order is valid!")
}
}Complete Model Validation
package main
import (
"fmt"
"github.com/mrz1836/go-validate"
)
// Customer model with comprehensive validation
type Customer struct {
// Basic info with struct tags
FirstName string `validation:"min_length=2 max_length=50"`
LastName string `validation:"min_length=2 max_length=50"`
Email string `validation:"format=email"`
Age uint8 `validation:"min=18 max=120"`
// Address info
Address string `validation:"min_length=10 max_length=200"`
City string `validation:"min_length=2 max_length=50"`
State string `validation:"min_length=2 max_length=2"` // US state codes
ZipCode string `validation:"format=regexp:^[0-9]{5}(-[0-9]{4})?$"`
// Contact info (validated separately)
Phone string `json:"phone"`
SocialSecurityNumber string `json:"-"`
// Account info
AccountType string `validation:"min_length=1"`
InitialBalance float64 `validation:"min=0"`
}
// Custom validation method that combines struct tags with utility functions
func (c *Customer) Validate() (bool, []validate.ValidationError) {
// First run struct tag validations
_, errors := validate.IsValid(*c)
// Add phone number validation
if valid, err := validate.IsValidPhoneNumber(c.Phone, "1"); !valid && c.Phone != "" {
errors = append(errors, validate.ValidationError{
Key: "Phone",
Message: err.Error(),
})
}
// Add SSN validation
if valid, err := validate.IsValidSocial(c.SocialSecurityNumber); !valid {
errors = append(errors, validate.ValidationError{
Key: "SocialSecurityNumber",
Message: err.Error(),
})
}
// Add account type enum validation
allowedTypes := []string{"checking", "savings", "business", "premium"}
if valid, err := validate.IsValidEnum(c.AccountType, &allowedTypes, false); !valid {
errors = append(errors, validate.ValidationError{
Key: "AccountType",
Message: err.Error(),
})
}
return len(errors) == 0, errors
}
func main() {
validate.InitValidations()
customer := Customer{
FirstName: "Alice",
LastName: "Johnson",
Email: "alice.johnson@email.com",
Age: 28,
Address: "123 Main Street, Apt 4B",
City: "New York",
State: "NY",
ZipCode: "10001",
Phone: "555-123-4567",
SocialSecurityNumber: "123-45-6789", // This will fail validation (blacklisted)
AccountType: "checking",
InitialBalance: 1000.00,
}
isValid, errors := customer.Validate()
if !isValid {
fmt.Printf("Customer validation failed with %d errors:\n", len(errors))
for i, err := range errors {
fmt.Printf("%d. %s\n", i+1, err.Error())
}
} else {
fmt.Println("Customer validation passed! Ready to save to database.")
}
}Run the Go benchmarks:
magex benchRead more about this Go project's code standards.
Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with AI assistants.
![]() |
|---|
| MrZ |
View the contributing guidelines and please follow the code of conduct.
All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀
