⚡ go-validate

Powerful struct field validation via tags plus extra validation utilities.

CI / CD	Quality & Security	Docs & Meta	Community

Table of Contents

• Installation
• Documentation
• Examples & Tests
• Benchmarks
• Code Standards
• AI Compliance
• Maintainers
• Contributing
• License

Installation

go-validate requires a supported release of Go.

go get github.com/mrz1836/go-validate

Documentation

View the generated documentation

Heads up! go-validate is intentionally light on dependencies. The only external package it uses is the excellent testify suite—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:install

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The 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

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Build Commands

View all build commands

magex help

GitHub Workflows

The Workflow Control Center

All GitHub Actions workflows in this repository are powered by configuration files: .env.base (default configuration) and optionally .env.custom (project-specific overrides) – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

Configuration Files:

• .env.base – Default configuration that works for most Go projects
• .env.custom – Optional project-specific overrides

This magical file controls everything from:

• 🚀 Go version matrix (test on multiple versions or just one)
• 🏃 Runner selection (Ubuntu or macOS, your wallet decides)
• 🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
• 🛡️ Security tool versions (gitleaks, nancy, govulncheck)
• 🤖 Auto-merge behaviors (how aggressive should the bots be?)
• 🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Pro tip: Want to disable code coverage? Just add ENABLE_CODE_COVERAGE=false to your .env.custom to override the default in .env.base and push. No YAML archaeology required!

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml	Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml	Automatically merges Dependabot PRs that meet all requirements.
fortress.yml	Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml	Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml	Runs OpenSSF Scorecard to assess supply chain security.
stale.yml	Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml	Keeps GitHub labels in sync with the declarative manifest at .github/labels.yml.

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

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

Examples & Tests

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 test

Run all tests with race detector (slower):

magex test:race

Examples demonstrating various validation scenarios.

Basic 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.")
    }
}

Benchmarks

Run the Go benchmarks:

magex bench

Code Standards

Read more about this Go project's code standards.

AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

• AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
• CLAUDE.md — quick checklist for the Claude agent.
• .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
• sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

Maintainers

MrZ

Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

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! 🚀

License