sriniously/god

README

God - A Zod-like Validation Library for Go

God is a comprehensive validation library for Go that provides type-safe schema validation with a fluent API, inspired by Zod from the TypeScript ecosystem.

Features

Type-safe validation with comprehensive error messages
Fluent API for building complex validation schemas
Primitive types: String, Number, Boolean, Date validation
Complex types: Object, Array, Tuple validation
Advanced features: Union types, Discriminated unions, Enums, Literals
Flexible constraints: Min/Max, Regex, Email, URL validation
Transformations: String trimming, case conversion
Optional and default values support
Nested validation with detailed error paths
Lazy evaluation for recursive schemas

Installation

go get github.com/sriniously/god

Quick Start

package main

import (
    "fmt"
    "github.com/sriniously/god"
)

func main() {
    // Define a user schema
    userSchema := god.Object(map[string]god.Schema{
        "name":  god.String().Min(2).Max(50),
        "email": god.String().Email(),
        "age":   god.Int().Min(0).Max(120),
    })

    // Validate data
    user := map[string]interface{}{
        "name":  "John Doe",
        "email": "john@example.com",
        "age":   30,
    }

    result := userSchema.Validate(user)
    if result.Valid {
        fmt.Println("Validation passed!")
        // Access validated data
        validated := result.Value.(map[string]interface{})
        fmt.Printf("Name: %s\n", validated["name"])
    } else {
        fmt.Printf("Validation failed: %v\n", result.Error())
    }
}

Core Types

String Validation

schema := god.String().Min(5).Max(100).Email()
schema = god.String().Regex(`^[a-zA-Z0-9]+$`)
schema = god.String().URL()
schema = god.String().UUID()

// Transformations
schema = god.String().Trim().ToLower()
schema = god.String().ToUpper()

Number Validation

schema := god.Number().Min(0).Max(100)
schema = god.Int().Positive()
schema = god.Number().Negative()
schema = god.Number().NonNegative()
schema = god.Number().MultipleOf(5)

Boolean Validation

schema := god.Boolean()
schema = god.Bool() // Alias

Date Validation

schema := god.Date()
schema = god.Date().Min(time.Now())
schema = god.Date().Max(time.Date(2025, 12, 31, 0, 0, 0, 0, time.UTC))

Complex Types

Object Validation

userSchema := god.Object(map[string]god.Schema{
    "id":       god.Int().Positive(),
    "name":     god.String().Min(1).Max(100),
    "email":    god.String().Email(),
    "age":      god.Int().Min(0).Max(120).Optional(),
    "isActive": god.Boolean().Default(true),
})

// Object operations
schema = userSchema.Partial()        // Make all fields optional
schema = userSchema.RequiredFields("name", "email")  // Require specific fields
schema = userSchema.Pick("name", "email")            // Pick specific fields
schema = userSchema.Omit("id")                       // Omit specific fields
schema = userSchema.Strict()                         // Disallow unknown fields
schema = userSchema.Passthrough()                    // Allow unknown fields

Array Validation

schema := god.Array(god.String()).Min(1).Max(10)
schema = god.Array(god.Int()).Nonempty()

Tuple Validation

// Fixed-length tuple
coordinateSchema := god.Tuple(god.Number(), god.Number(), god.Number())

// Tuple with rest elements
csvSchema := god.Tuple(god.String(), god.String()).Rest(god.Union(god.String(), god.Number()))

Advanced Features

Union Types

// Simple union
schema := god.Union(god.String(), god.Number())

// Discriminated union
shapeSchema := god.DiscriminatedUnion("type", map[string]god.Schema{
    "circle": god.Object(map[string]god.Schema{
        "type":   god.Literal("circle"),
        "radius": god.Number().Positive(),
    }),
    "rectangle": god.Object(map[string]god.Schema{
        "type":   god.Literal("rectangle"),
        "width":  god.Number().Positive(),
        "height": god.Number().Positive(),
    }),
})

Enums and Literals

// Enum validation
roleSchema := god.Enum("user", "admin", "moderator")

// Literal validation
typeSchema := god.Literal("success")

Nullable Types

schema := god.Nullable(god.String())

Utility Types

schema := god.Any()        // Accepts any value
schema = god.Unknown()     // Accepts any value (alias for Any)
schema = god.Void()        // Always returns nil
schema = god.Never()       // Always fails validation

Lazy Evaluation

// For recursive schemas
var nodeSchema god.Schema
nodeSchema = god.Lazy(func() god.Schema {
    return god.Object(map[string]god.Schema{
        "value":    god.String(),
        "children": god.Array(nodeSchema).Optional(),
    })
})

Optional and Default Values

schema := god.Object(map[string]god.Schema{
    "name":     god.String(),
    "email":    god.String().Email().Optional(),
    "isActive": god.Boolean().Default(true),
    "role":     god.Enum("user", "admin").Default("user"),
})

Error Handling

result := schema.Validate(data)
if !result.Valid {
    for _, err := range result.Errors {
        fmt.Printf("Field: %s, Error: %s, Code: %s\n", err.Field, err.Message, err.Code)
    }
    
    // Or get formatted error
    fmt.Printf("Error: %v\n", result.Error())
}

Transformations

God supports data transformations during validation:

userSchema := god.Object(map[string]god.Schema{
    "name":     god.String().Trim(),
    "email":    god.String().ToLower().Email(),
    "username": god.String().ToLower().Regex(`^[a-z0-9_]+$`),
})

// Input data with extra whitespace and mixed case
input := map[string]interface{}{
    "name":     "  John Doe  ",
    "email":    "  JOHN@EXAMPLE.COM  ",
    "username": "JOHN_DOE",
}

result := userSchema.Validate(input)
if result.Valid {
    validated := result.Value.(map[string]interface{})
    // validated["name"] = "John Doe"
    // validated["email"] = "john@example.com"
    // validated["username"] = "john_doe"
}

Performance Considerations

Schemas are reusable and thread-safe
Compile schemas once and reuse them
Use Lazy() for recursive schemas to avoid infinite recursion
Consider using Strict() on objects when you don't need unknown fields

Examples

See example_test.go for comprehensive examples including:

User registration validation
API request validation
Complex nested object validation
Discriminated union validation
Array and tuple validation
Data transformation examples

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

README

God - A Zod-like Validation Library for Go

God is a comprehensive validation library for Go that provides type-safe schema validation with a fluent API, inspired by Zod from the TypeScript ecosystem.

Features

Type-safe validation with comprehensive error messages
Fluent API for building complex validation schemas
Primitive types: String, Number, Boolean, Date validation
Complex types: Object, Array, Tuple validation
Advanced features: Union types, Discriminated unions, Enums, Literals
Flexible constraints: Min/Max, Regex, Email, URL validation
Transformations: String trimming, case conversion
Optional and default values support
Nested validation with detailed error paths
Lazy evaluation for recursive schemas

Installation

go get github.com/sriniously/god

Quick Start

package main

import (
    "fmt"
    "github.com/sriniously/god"
)

func main() {
    // Define a user schema
    userSchema := god.Object(map[string]god.Schema{
        "name":  god.String().Min(2).Max(50),
        "email": god.String().Email(),
        "age":   god.Int().Min(0).Max(120),
    })

    // Validate data
    user := map[string]interface{}{
        "name":  "John Doe",
        "email": "john@example.com",
        "age":   30,
    }

    result := userSchema.Validate(user)
    if result.Valid {
        fmt.Println("Validation passed!")
        // Access validated data
        validated := result.Value.(map[string]interface{})
        fmt.Printf("Name: %s\n", validated["name"])
    } else {
        fmt.Printf("Validation failed: %v\n", result.Error())
    }
}

Core Types

String Validation

schema := god.String().Min(5).Max(100).Email()
schema = god.String().Regex(`^[a-zA-Z0-9]+$`)
schema = god.String().URL()
schema = god.String().UUID()

// Transformations
schema = god.String().Trim().ToLower()
schema = god.String().ToUpper()

Number Validation

schema := god.Number().Min(0).Max(100)
schema = god.Int().Positive()
schema = god.Number().Negative()
schema = god.Number().NonNegative()
schema = god.Number().MultipleOf(5)

Boolean Validation

schema := god.Boolean()
schema = god.Bool() // Alias

Date Validation

schema := god.Date()
schema = god.Date().Min(time.Now())
schema = god.Date().Max(time.Date(2025, 12, 31, 0, 0, 0, 0, time.UTC))

Complex Types

Object Validation

userSchema := god.Object(map[string]god.Schema{
    "id":       god.Int().Positive(),
    "name":     god.String().Min(1).Max(100),
    "email":    god.String().Email(),
    "age":      god.Int().Min(0).Max(120).Optional(),
    "isActive": god.Boolean().Default(true),
})

// Object operations
schema = userSchema.Partial()        // Make all fields optional
schema = userSchema.RequiredFields("name", "email")  // Require specific fields
schema = userSchema.Pick("name", "email")            // Pick specific fields
schema = userSchema.Omit("id")                       // Omit specific fields
schema = userSchema.Strict()                         // Disallow unknown fields
schema = userSchema.Passthrough()                    // Allow unknown fields

Array Validation

schema := god.Array(god.String()).Min(1).Max(10)
schema = god.Array(god.Int()).Nonempty()

Tuple Validation

// Fixed-length tuple
coordinateSchema := god.Tuple(god.Number(), god.Number(), god.Number())

// Tuple with rest elements
csvSchema := god.Tuple(god.String(), god.String()).Rest(god.Union(god.String(), god.Number()))

Advanced Features

Union Types

// Simple union
schema := god.Union(god.String(), god.Number())

// Discriminated union
shapeSchema := god.DiscriminatedUnion("type", map[string]god.Schema{
    "circle": god.Object(map[string]god.Schema{
        "type":   god.Literal("circle"),
        "radius": god.Number().Positive(),
    }),
    "rectangle": god.Object(map[string]god.Schema{
        "type":   god.Literal("rectangle"),
        "width":  god.Number().Positive(),
        "height": god.Number().Positive(),
    }),
})

Enums and Literals

// Enum validation
roleSchema := god.Enum("user", "admin", "moderator")

// Literal validation
typeSchema := god.Literal("success")

Nullable Types

schema := god.Nullable(god.String())

Utility Types

schema := god.Any()        // Accepts any value
schema = god.Unknown()     // Accepts any value (alias for Any)
schema = god.Void()        // Always returns nil
schema = god.Never()       // Always fails validation

Lazy Evaluation

// For recursive schemas
var nodeSchema god.Schema
nodeSchema = god.Lazy(func() god.Schema {
    return god.Object(map[string]god.Schema{
        "value":    god.String(),
        "children": god.Array(nodeSchema).Optional(),
    })
})

Optional and Default Values

schema := god.Object(map[string]god.Schema{
    "name":     god.String(),
    "email":    god.String().Email().Optional(),
    "isActive": god.Boolean().Default(true),
    "role":     god.Enum("user", "admin").Default("user"),
})

Error Handling

result := schema.Validate(data)
if !result.Valid {
    for _, err := range result.Errors {
        fmt.Printf("Field: %s, Error: %s, Code: %s\n", err.Field, err.Message, err.Code)
    }
    
    // Or get formatted error
    fmt.Printf("Error: %v\n", result.Error())
}

Transformations

God supports data transformations during validation:

userSchema := god.Object(map[string]god.Schema{
    "name":     god.String().Trim(),
    "email":    god.String().ToLower().Email(),
    "username": god.String().ToLower().Regex(`^[a-z0-9_]+$`),
})

// Input data with extra whitespace and mixed case
input := map[string]interface{}{
    "name":     "  John Doe  ",
    "email":    "  JOHN@EXAMPLE.COM  ",
    "username": "JOHN_DOE",
}

result := userSchema.Validate(input)
if result.Valid {
    validated := result.Value.(map[string]interface{})
    // validated["name"] = "John Doe"
    // validated["email"] = "john@example.com"
    // validated["username"] = "john_doe"
}

Performance Considerations

Schemas are reusable and thread-safe
Compile schemas once and reuse them
Use Lazy() for recursive schemas to avoid infinite recursion
Consider using Strict() on objects when you don't need unknown fields

Examples

See example_test.go for comprehensive examples including:

User registration validation
API request validation
Complex nested object validation
Discriminated union validation
Array and tuple validation
Data transformation examples

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

sriniously/god(opens in a new tab)

README

God - A Zod-like Validation Library for Go

Features

Installation

Quick Start

Core Types

String Validation

Number Validation

Boolean Validation

Date Validation

Complex Types

Object Validation

Array Validation

Tuple Validation

Advanced Features

Union Types

Enums and Literals

Nullable Types

Utility Types

Lazy Evaluation

Optional and Default Values

Error Handling

Transformations

Performance Considerations

Examples

License

Contributing

README

God - A Zod-like Validation Library for Go

Features

Installation

Quick Start

Core Types

String Validation

Number Validation

Boolean Validation

Date Validation

Complex Types

Object Validation

Array Validation

Tuple Validation

Advanced Features

Union Types

Enums and Literals

Nullable Types

Utility Types

Lazy Evaluation

Optional and Default Values

Error Handling

Transformations

Performance Considerations

Examples

License

Contributing