envvalidator

README

go-env-validator

Struct-based environment variable validation with batch error reporting for Go

Installation

go get github.com/philiprehberger/go-env-validator

Usage

Define a Config Struct

import "github.com/philiprehberger/go-env-validator"

type Config struct {
    Port     int           `env:"PORT,default=3000"`
    Database string        `env:"DATABASE_URL,required"`
    Debug    bool          `env:"DEBUG,default=false"`
    Env      string        `env:"APP_ENV,required,choices=development|staging|production"`
    Timeout  time.Duration `env:"TIMEOUT,default=30s"`
}

Validate from Environment

var cfg Config
if err := envvalidator.Validate(&cfg); err != nil {
    log.Fatal(err)
}
fmt.Println(cfg.Port) // 3000

Validate from Map (Testing)

var cfg Config
err := envvalidator.ValidateFrom(&cfg, map[string]string{
    "DATABASE_URL": "postgres://localhost/mydb",
    "APP_ENV":      "development",
})

Batch Error Reporting

if err := envvalidator.Validate(&cfg); err != nil {
    var ve *envvalidator.ValidationError
    if errors.As(err, &ve) {
        for _, e := range ve.Errors {
            fmt.Println(e)
        }
    }
}

Supported Types

• string
• int, int8, int16, int32, int64
• uint, uint8, uint16, uint32, uint64
• float32, float64
• bool — accepts true, false, 1, 0, t, f, T, F, TRUE, FALSE
• time.Duration — Go duration strings (e.g., "30s", "5m", "1h30m")
• url.URL — parsed via url.Parse
• Any type implementing encoding.TextUnmarshaler

Tag Options

• required — field must be set in environment
• default=VALUE — fallback if not set (validated against choices if both present)
• choices=A|B|C — restrict to specific values (whitespace around | is trimmed)

API

Function / Method	Description
Validate(dst any) error	Populate struct from environment variables and validate
ValidateFrom(dst any, source map[string]string) error	Populate struct from a map instead of os.Getenv
ValidationError	Error type containing all validation errors
(*ValidationError) Error() string	Format all collected errors as a single string

Development

go test ./...
go vet ./...

License

MIT

Documentation

Overview

Package envvalidator provides struct-based environment variable validation for Go.

Index

• func Validate(dst any) error
• func ValidateFrom(dst any, source map[string]string) error
• type ValidationError
  • func (e *ValidationError) Error() string

Functions

func Validate

func Validate(dst any) error

Validate populates the given struct pointer from environment variables. Struct fields are configured via the `env` tag:

type Config struct {
    Port     int    `env:"PORT,default=3000"`
    Database string `env:"DATABASE_URL,required"`
    Debug    bool   `env:"DEBUG"`
}

func ValidateFrom

func ValidateFrom(dst any, source map[string]string) error

ValidateFrom populates the struct from the given source map instead of os.Getenv.

Types

type ValidationError

type ValidationError struct {
	Errors []string
}

ValidationError contains all validation errors collected during parsing.

func (*ValidationError) Error

func (e *ValidationError) Error() string