Rules API Reference

This reference documents all built-in validation rules available in Souuup. Rules are organized by the type of data they validate.

String Rules

String rules are found in the r package and work with string values.

Length Validation

`r.MinS(n int) StringRule`

Validates that a string has at least n characters.

// Minimum 3 characters
nameField := u.Field("John", r.MinS(3))

Parameters:

n - Minimum length (inclusive)

Error Message: "length is X, but needs to be at least N"

`r.MaxS(n int) StringRule`

Validates that a string has at most n characters.

// Maximum 20 characters
usernameField := u.Field("johndoe", r.MaxS(20))

Parameters:

n - Maximum length (inclusive)

Error Message: "length is X, but needs to be at most N"

`r.LenS(n int) StringRule`

Validates that a string has exactly n characters.

// Exactly 6 characters (e.g., for PIN codes)
pinField := u.Field("123456", r.LenS(6))

Parameters:

n - Exact length required

Error Message: "length is X, but needs to be exactly N"

Content Validation

`r.ContainsS(substr string) StringRule`

Validates that a string contains the specified substring.

// Must contain "@" symbol
emailField := u.Field("[email protected]", r.ContainsS("@"))

Parameters:

substr - Substring that must be present

Error Message: "\"value\" does not contain \"substr\", but needs to"

`r.InS(set []string) StringRule`

Validates that a string is one of the values in the provided set.

// Must be one of the allowed sizes
sizeField := u.Field("medium", r.InS([]string{"small", "medium", "large"}))

Parameters:

set - Slice of allowed string values

Error Message: "\"value\" is not in [allowed values], but should be"

`r.NotInS(set []string) StringRule`

Validates that a string is NOT one of the values in the provided set.

// Must not be a forbidden word
usernameField := u.Field("john", r.NotInS([]string{"admin", "root", "system"}))

Parameters:

set - Slice of forbidden string values

Error Message: "\"value\" is in [forbidden values], but shouldn't be"

Numeric Rules

Numeric rules work with any type that implements the Numeric constraint (integers and floats).

Comparison Rules

`r.MinN[T Numeric](n T) NumericRule[T]`

Validates that a numeric value is at least n.

// Age must be at least 18
ageField := u.Field(25, r.MinN(18))

// Price must be at least 0.01
priceField := u.Field(19.99, r.MinN(0.01))

Parameters:

n - Minimum value (inclusive)

Error Message: "value is X, but needs to be at least N"

`r.MaxN[T Numeric](n T) NumericRule[T]`

Validates that a numeric value is at most n.

// Age must not exceed 120
ageField := u.Field(25, r.MaxN(120))

Parameters:

n - Maximum value (inclusive)

Error Message: "value is X, but needs to be at most N"

`r.Gt[T Numeric](n T) NumericRule[T]`

Validates that a numeric value is greater than n (exclusive).

// Price must be greater than 0
priceField := u.Field(19.99, r.Gt(0.0))

Parameters:

n - Value that must be exceeded

Error Message: "value is X, but needs to be greater than N"

`r.Gte[T Numeric](n T) NumericRule[T]`

Validates that a numeric value is greater than or equal to n. This is an alias for MinN.

// Score must be at least 0
scoreField := u.Field(85, r.Gte(0))

Parameters:

n - Minimum value (inclusive)

Error Message: "value is X, but needs to be at least N"

`r.Lt[T Numeric](n T) NumericRule[T]`

Validates that a numeric value is less than n (exclusive).

// Percentage must be less than 100
percentField := u.Field(85.5, r.Lt(100.0))

Parameters:

n - Value that must not be reached

Error Message: "value is X, but needs to be less than N"

`r.Lte[T Numeric](n T) NumericRule[T]`

Validates that a numeric value is less than or equal to n. This is an alias for MaxN.

// Score must not exceed 100
scoreField := u.Field(85, r.Lte(100))

Parameters:

n - Maximum value (inclusive)

Error Message: "value is X, but needs to be at most N"

`r.NeqN[T Numeric](n T) NumericRule[T]`

Validates that a numeric value is not equal to n.

// Quantity cannot be 0
quantityField := u.Field(5, r.NeqN(0))

Parameters:

n - Value that is not allowed

Error Message: "value is X, but needs to not equal to N"

Slice Rules

Slice rules validate arrays/slices and their elements.

Length Rules

`r.MinLen[T any](n int) SliceRule[T]`

Validates that a slice has at least n elements.

// Must have at least 1 interest
interestsField := u.Field([]string{"coding", "music"}, r.MinLen[string](1))

Parameters:

n - Minimum number of elements

Error Message: "length is X, but needs to be at least N"

`r.MaxLen[T any](n int) SliceRule[T]`

Validates that a slice has at most n elements.

// Can have at most 5 tags
tagsField := u.Field([]string{"go", "validation"}, r.MaxLen[string](5))

Parameters:

n - Maximum number of elements

Error Message: "length is X, but needs to be at most N"

`r.ExactLen[T any](n int) SliceRule[T]`

Validates that a slice has exactly n elements.

// Must have exactly 3 coordinates
coordsField := u.Field([]float64{1.0, 2.0, 3.0}, r.ExactLen[float64](3))

Parameters:

n - Exact number of elements required

Error Message: "length is X, but needs to be exactly N"

Element Validation

`r.Every[T any](rule Rule[T]) SliceRule[T]`

Validates that every element in the slice passes the given rule.

// Every interest must be at least 3 characters
interestsField := u.Field([]string{"coding", "music"}, r.Every(r.MinS(3)))

// Every score must be between 0 and 100
scoresField := u.Field([]int{85, 92, 78}, r.Every(r.MinN(0)), r.Every(r.MaxN(100)))

Parameters:

rule - The rule that every element must satisfy

Error Message: "X elements failed validation\n [index]: error message"

`r.Some[T any](rule Rule[T]) SliceRule[T]`

Validates that at least one element in the slice passes the given rule.

// At least one score must be above 90
scoresField := u.Field([]int{85, 95, 78}, r.Some(r.Gt(90)))

Parameters:

rule - The rule that at least one element must satisfy

Error Message: "all X elements failed validation\n [index]: error message"

`r.None[T any](rule Rule[T]) SliceRule[T]`

Validates that no element in the slice passes the given rule.

// No score should be negative
scoresField := u.Field([]int{85, 92, 78}, r.None(r.Lt(0)))

Parameters:

rule - The rule that no element should satisfy

Error Message: "X elements unexpectedly passed validation (expected none to pass rule)\n [index]: failed"

Content Rules

`r.Contains[T comparable](member T) SliceRule[T]`

Validates that a slice contains the specified element.

// Team must include a goalkeeper
positionsField := u.Field([]string{"GK", "DEF", "MID"}, r.Contains("GK"))

Parameters:

member - Element that must be present in the slice

Error Message: "[slice] does not contain member, but needs to"

General Rules

Rules that work with any comparable type.

`r.NotZero[T comparable](FieldState[T]) error`

Validates that a value is not the zero value for its type. This is the primary way to mark fields as required.

// String must not be empty
nameField := u.Field("John", r.NotZero)

// Number must not be 0
ageField := u.Field(25, r.NotZero)

// Boolean must be true
termsField := u.Field(true, r.NotZero)

Error Message: "value is required but has zero value"

`r.SameAs[T comparable](other T) Rule[T]`

Validates that a value equals another value. Commonly used for password confirmation.

// Password confirmation must match
confirmField := u.Field(confirmPassword, r.SameAs(originalPassword))

Parameters:

other - The value that this field must equal

Error Message: "X does not match Y"

Rule Composition

Combining Rules

You can apply multiple rules to a single field. All rules must pass for validation to succeed:

// Username with multiple constraints
usernameField := u.Field("johndoe",
    r.NotZero,    // Required
    r.MinS(3),    // At least 3 characters
    r.MaxS(20),   // At most 20 characters
    CustomUsernameRule, // Custom validation
)

Type Safety

All rules are type-safe through Go generics:

// These will compile
stringField := u.Field("hello", r.MinS(3))           // ✅
intField := u.Field(42, r.MinN(0))                   // ✅
sliceField := u.Field([]string{"a"}, r.MinLen[string](1)) // ✅

// These will NOT compile
stringField := u.Field("hello", r.MinN(0))          // ❌ Type mismatch
intField := u.Field(42, r.MinS(3))                  // ❌ Type mismatch

Error Messages

All built-in rules provide clear, actionable error messages that specify:

Current value - What was actually provided
Expected constraint - What the rule requires
Specific requirement - Exactly what needs to be fixed

Examples

// Input: age = 15, rule: r.MinN(18)
// Error: "value is 15, but needs to be at least 18"

// Input: name = "Jo", rule: r.MinS(3)
// Error: "length is 2, but needs to be at least 3"

// Input: tags = ["a", "bb", "c"], rule: r.Every(r.MinS(2))
// Error: "2 elements failed validation
//   [0]: length is 1, but needs to be at least 2
//   [2]: length is 1, but needs to be at least 2"

Best Practices

Use Specific Rules

Choose the most specific rule for your needs rather than generic ones.

// Good
r.MinN(18), r.MaxN(120)

// Less specific
CustomAgeRule()

Combine Rules Logically

Apply rules in logical order, from most basic to most specific.

// Good order
r.NotZero,      // Required first
r.MinS(8),      // Then length
StrongPassword, // Then complexity

Leverage Type Safety

Let the type system catch mistakes at compile time.

// Compiler ensures rule matches field type
u.Field(userAge, r.MinN(18)) // ✅ Correct
u.Field(userAge, r.MinS(18)) // ❌ Won't compile

Read Error Messages

Built-in rules provide detailed error messages to help debug validation failures.

{
  "age": {
    "errors": ["value is 15, but needs to be at least 18"]
  }
}

Next Steps

Custom Rules

Learn how to create your own validation rules for domain-specific requirements.

Custom Rules →

Examples

See real-world examples of using these rules in various scenarios.

Examples →

Core API

Explore the core validation framework functions and types.

Core API →