Constraints Overview

Constraints are validation rules applied to struct fields via struct tags. Pedantigo provides a comprehensive set of built-in constraints covering everything from basic requirements to complex format validation.

Constraint Syntax

Constraints are specified using the validate struct tag. Multiple constraints can be combined with commas, and some accept parameters:

type User struct {
    // Basic constraint
    Name     string `json:"name" validate:"required"`

    // Multiple constraints
    Email    string `json:"email" validate:"required,email"`

    // Constraints with parameters
    Age      int    `json:"age" validate:"required,min=18,max=120"`
    Username string `json:"username" validate:"minLength=3,maxLength=20,pattern=^[a-z0-9_]+$"`
}

Constraint Categories

Core Constraints

The fundamental constraints applicable across multiple types:

Constraint	Parameter	Description	Example
required	None	Field must be present in the input	validate:"required"
omitempty	None	Skip regular constraints when the field is at its zero value; cross-field constraints still run	validate:"omitempty,email"
min	Numeric	Minimum value (numeric) or length (string)	validate:"min=18"
max	Numeric	Maximum value (numeric) or length (string)	validate:"max=100"
gt	Numeric	Greater than	validate:"gt=0"
gte	Numeric	Greater than or equal	validate:"gte=1"
lt	Numeric	Less than	validate:"lt=100"
lte	Numeric	Less than or equal	validate:"lte=99"
eq	Value	Must equal exact value	validate:"eq=active"
ne	Value	Must NOT equal value	validate:"ne=banned"
oneof	Space-separated values	Must be one of specified values	validate:"oneof=red green blue"
oneofci	Space-separated values	Case-insensitive oneof	validate:"oneofci=admin user guest"
len	Numeric	Exact length (strings/arrays)	validate:"len=32"

See the Numeric Constraints page for detailed numeric range examples. See omitempty as a Validation Constraint for the full omitempty reference including cross-field interaction.

String Constraints

Specialized constraints for string validation:

Constraint	Parameter	Description	Example
minLength	Numeric	Minimum string length	validate:"minLength=3"
maxLength	Numeric	Maximum string length	validate:"maxLength=100"
alpha	None	Only alphabetic characters	validate:"alpha"
alphanum	None	Only letters and numbers	validate:"alphanum"
ascii	None	Only ASCII characters	validate:"ascii"
lowercase	None	Must be lowercase	validate:"lowercase"
uppercase	None	Must be uppercase	validate:"uppercase"
contains	String	Must contain substring	validate:"contains=test"
excludes	String	Must not contain substring	validate:"excludes=forbidden"
startswith	String	Must start with prefix	validate:"startswith=https://"
endswith	String	Must end with suffix	validate:"endswith=.com"
strip_whitespace	None	No leading/trailing whitespace	validate:"strip_whitespace"
pattern	Regex	Match regex pattern	validate:"pattern=^[a-z]+$"
regexp	Regex	Match regex pattern (alias)	validate:"regexp=^[a-z]+$"

See the String Constraints page for detailed string validation examples.

Numeric Constraints

Additional constraints specific to numeric types:

Constraint	Parameter	Description	Example
positive	None	Must be greater than zero	validate:"positive"
negative	None	Must be less than zero	validate:"negative"
multiple_of	Numeric	Must be divisible by value	validate:"multiple_of=5"
max_digits	Numeric	Maximum total digits	validate:"max_digits=8"
decimal_places	Numeric	Maximum decimal places	validate:"decimal_places=2"
disallow_inf_nan	None	Reject infinity and NaN values	validate:"disallow_inf_nan"

See the Numeric Constraints page for detailed numeric validation examples.

Format Constraints

Constraints for common data formats:

Constraint	Description	Example
email	Valid email address format	validate:"email"
url	Valid URL format	validate:"url"
uri	Valid URI format	validate:"uri"
uuid	Valid UUID (any version)	validate:"uuid"
ipv4	Valid IPv4 address	validate:"ipv4"
ipv6	Valid IPv6 address	validate:"ipv6"
ip	Valid IPv4 or IPv6 address	validate:"ip"
cidr	Valid CIDR notation (IPv4 or IPv6)	validate:"cidr"
cidrv4	Valid IPv4 CIDR notation	validate:"cidrv4"
cidrv6	Valid IPv6 CIDR notation	validate:"cidrv6"
mac	Valid MAC address	validate:"mac"
hostname	Valid hostname	validate:"hostname"
hostname_rfc1123	Valid RFC 1123 hostname	validate:"hostname_rfc1123"
fqdn	Valid fully qualified domain name	validate:"fqdn"
port	Valid port number (0-65535)	validate:"port"
tcp_addr	Valid TCP address	validate:"tcp_addr"
udp_addr	Valid UDP address	validate:"udp_addr"
tcp4_addr	Valid TCP4 address	validate:"tcp4_addr"
json	Valid JSON string	validate:"json"
jwt	Valid JSON Web Token	validate:"jwt"
semver	Valid semantic version	validate:"semver"
cron	Valid cron expression	validate:"cron"
datetime	Matches Go time layout	validate:"datetime=2006-01-02"
ulid	Valid ULID format	validate:"ulid"

See the Format Constraints page for detailed format validation examples.

Encoding Constraints

Constraints for encoded data formats:

Constraint	Description	Example
base64	Valid base64 encoding	validate:"base64"
base64url	Valid URL-safe base64 encoding	validate:"base64url"
base64rawurl	Valid raw URL-safe base64 encoding	validate:"base64rawurl"

Hash Constraints

Constraints for validating hash format strings:

Constraint	Description	Example
md5	Valid MD5 hash format	validate:"md5"
sha256	Valid SHA256 hash format	validate:"sha256"
sha384	Valid SHA384 hash format	validate:"sha384"
sha512	Valid SHA512 hash format	validate:"sha512"
mongodb	Valid MongoDB ObjectID format	validate:"mongodb"

Finance Constraints

Constraints for financial and cryptocurrency identifiers:

Constraint	Description	Example
credit_card	Valid credit card number (Luhn check)	validate:"credit_card"
luhn_checksum	Valid Luhn checksum	validate:"luhn_checksum"
btc_addr	Valid Bitcoin address (P2PKH/P2SH)	validate:"btc_addr"
btc_addr_bech32	Valid Bitcoin bech32 address	validate:"btc_addr_bech32"
eth_addr	Valid Ethereum address	validate:"eth_addr"

Identity Constraints

Constraints for identification numbers and codes:

Constraint	Description	Example
isbn	Valid ISBN (10 or 13)	validate:"isbn"
isbn10	Valid ISBN-10	validate:"isbn10"
isbn13	Valid ISBN-13	validate:"isbn13"
issn	Valid ISSN format	validate:"issn"
ssn	Valid US Social Security Number	validate:"ssn"
ein	Valid US Employer Identification Number	validate:"ein"
e164	Valid E.164 phone number format	validate:"e164"

Geographic Constraints

Constraints for geographic coordinates:

Constraint	Description	Example
latitude	Valid latitude (-90 to 90)	validate:"latitude"
longitude	Valid longitude (-180 to 180)	validate:"longitude"

Color Constraints

Constraints for color format validation:

Constraint	Description	Example
hexcolor	Valid hex color (#RGB or #RRGGBB)	validate:"hexcolor"
rgb	Valid RGB color	validate:"rgb"
rgba	Valid RGBA color	validate:"rgba"
hsl	Valid HSL color	validate:"hsl"
hsla	Valid HSLA color	validate:"hsla"

ISO Constraints

Constraints for ISO standard codes and formats:

Constraint	Parameter	Description	Example
iso3166_alpha2	None	ISO 3166-1 alpha-2 country code	validate:"iso3166_alpha2"
iso3166_alpha2_eu	None	ISO 3166-1 alpha-2 EU country code	validate:"iso3166_alpha2_eu"
iso3166_alpha3	None	ISO 3166-1 alpha-3 country code	validate:"iso3166_alpha3"
iso3166_alpha3_eu	None	ISO 3166-1 alpha-3 EU country code	validate:"iso3166_alpha3_eu"
iso3166_numeric	None	ISO 3166-1 numeric country code	validate:"iso3166_numeric"
iso3166_2	None	ISO 3166-2 subdivision code	validate:"iso3166_2"
iso4217	None	ISO 4217 currency code	validate:"iso4217"
iso4217_numeric	None	ISO 4217 numeric currency code	validate:"iso4217_numeric"
postcode	Country code	Postal code for specific country	validate:"postcode=US"
postcode_iso3166_alpha2	Country code	Postal code (alias for postcode)	validate:"postcode_iso3166_alpha2=GB"
bcp47	None	BCP 47 language tag	validate:"bcp47"

Filesystem Constraints

Constraints for file and directory path validation:

Constraint	Description	Example
filepath	Valid file path	validate:"filepath"
dirpath	Valid directory path	validate:"dirpath"
file	Path must point to existing file	validate:"file"
dir	Path must point to existing directory	validate:"dir"

Collection Constraints

Constraints for arrays, slices, and maps:

Constraint	Parameter	Description	Example
minItems	Numeric	Minimum number of items	validate:"minItems=1"
maxItems	Numeric	Maximum number of items	validate:"maxItems=100"
unique	None	All items must be unique	validate:"unique"

See the Collection Constraints page for detailed collection validation examples.

Default Values

Constraint	Parameter	Description	Example
default	Value	Default value if field missing	validate:"default=active"

For slice fields, use space-separated values (consistent with oneof syntax):

Scopes []string `json:"scopes" validate:"default=read write"`
Tags   []string `json:"tags" validate:"default=general"`

Complete Example

Here's a realistic example combining constraints from multiple categories:

package main

import (
    "log"
    "github.com/SmrutAI/pedantigo/v2/validator"
)

type UserProfile struct {
    // Core constraints
    ID       string `json:"id" validate:"required,uuid"`
    Email    string `json:"email" validate:"required,email"`
    Username string `json:"username" validate:"required,minLength=3,maxLength=20,alphanum"`

    // String constraints
    Bio      string `json:"bio,omitempty" validate:"maxLength=500"`
    Website  string `json:"website,omitempty" validate:"url"`

    // Numeric constraints
    Age      int    `json:"age" validate:"min=13,max=120"`
    Rating   float64 `json:"rating,omitempty" validate:"min=0,max=5,decimal_places=1"`

    // Geographic constraints
    Latitude  float64 `json:"latitude,omitempty" validate:"latitude"`
    Longitude float64 `json:"longitude,omitempty" validate:"longitude"`

    // ISO constraints
    Country  string `json:"country,omitempty" validate:"iso3166_alpha2"`
    Currency string `json:"currency,omitempty" validate:"iso4217"`

    // Collection constraints
    Tags     []string `json:"tags,omitempty" validate:"maxItems=10,unique"`
    Roles    []string `json:"roles" validate:"minItems=1,oneof=admin moderator user"`

    // Enum constraint
    Status   string `json:"status" validate:"required,oneof=active inactive suspended"`
}

func main() {
    jsonData := []byte(`{
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "email": "alice@example.com",
        "username": "alice123",
        "bio": "Software engineer and open source enthusiast",
        "website": "https://example.com",
        "age": 28,
        "rating": 4.5,
        "latitude": 40.7128,
        "longitude": -74.0060,
        "country": "US",
        "currency": "USD",
        "tags": ["golang", "rust", "web"],
        "roles": ["user"],
        "status": "active"
    }`)

    user, err := validator.Unmarshal[UserProfile](jsonData)
    if err != nil {
        log.Fatalf("Validation failed: %v", err)
    }

    // user is now a fully validated UserProfile
    log.Printf("User: %+v", user)
}

Validation Error Handling

When validation fails, Pedantigo returns detailed errors for each field:

user, err := validator.Unmarshal[UserProfile](invalidData)
if err != nil {
    if validationErr, ok := err.(*validator.ValidationError); ok {
        for _, fieldErr := range validationErr.Errors {
            fmt.Printf("Field: %s, Error: %s\n", fieldErr.Field, fieldErr.Message)
        }
    }
}

Example validation error output:

Field: email, Error: must be a valid email address
Field: age, Error: must be at least 13
Field: rating, Error: must be at most 5
Field: roles, Error: field is required

Context-Aware Constraints

Some constraints behave differently depending on the field type:

• min/max: For numeric types, validates value range. For strings, validates length. For arrays, validates item count.
• gt/gte/lt/lte: Works with numeric types and comparable values.
• len: For strings, validates character count. For arrays/slices, validates element count.

Performance Considerations

Constraint validation in Pedantigo is highly optimized:

• Format constraints (email, URL, UUID, etc.) use compiled regex patterns cached at startup
• ISO code validation uses precompiled lookup tables
• Numeric constraints perform simple arithmetic comparisons
• String constraints use efficient string operations

See Schema Generation for caching strategy that provides 240x speedup.

Next Steps

Learn more about specific constraint categories:

• String Constraints - Detailed string validation
• Numeric Constraints - Detailed numeric validation
• Format Constraints - Email, URL, UUID, and more
• Collection Constraints - Array and slice validation
• Cross-Field Validation - Validate relationships between fields