validation

func WithContext ¶

func WithContext(ctx context.Context) Option

WithContext overrides the context used for validation. This is useful when you need a different context than the one passed to Validate().

Note: In most cases, you should simply pass the context directly to Validate(). This option exists for advanced use cases where context override is needed.

Example:

validator.Validate(requestCtx, &req, WithContext(backgroundCtx))

func WithCustomSchema ¶

func WithCustomSchema(id, schema string) Option

WithCustomSchema sets a custom JSON Schema for validation. This overrides any schema provided by the JSONSchemaProvider interface.

Example:

schema := `{"type": "object", "properties": {"email": {"type": "string", "format": "email"}}}`
validator.Validate(ctx, &req, WithCustomSchema("user-schema", schema))

func WithCustomTag ¶ added in v0.2.0

func WithCustomTag(name string, fn validator.Func) Option

WithCustomTag registers a custom validation tag for use in struct tags. Custom tags are registered when the Validator is created.

Example:

validator := validation.MustNew(
    validation.WithCustomTag("phone", func(fl validator.FieldLevel) bool {
        return phoneRegex.MatchString(fl.Field().String())
    }),
)

type User struct {
    Phone string `validate:"phone"`
}

func WithCustomValidator ¶

func WithCustomValidator(fn func(any) error) Option

WithCustomValidator sets a custom validation function. It calls the function before any other validation strategies.

Example:

validator.Validate(ctx, &req, WithCustomValidator(func(v any) error {
    req := v.(*UserRequest)
    if req.Age < 18 {
        return errors.New("must be 18 or older")
    }
    return nil
}))

func WithDisallowUnknownFields ¶

func WithDisallowUnknownFields(disallow bool) Option

WithDisallowUnknownFields rejects JSON with unknown fields (typo detection). When enabled, it causes BindJSONStrict to reject requests with fields not defined in the struct.

Example:

BindAndValidateStrict(&req, WithDisallowUnknownFields(true))

func WithFieldNameMapper ¶

func WithFieldNameMapper(mapper func(string) string) Option

WithFieldNameMapper sets a function to transform field names in error messages. It is useful for localization or custom naming conventions.

Example:

validator.Validate(ctx, &req, WithFieldNameMapper(func(name string) string {
    return strings.ReplaceAll(name, "_", " ")
}))

func WithMaxCachedSchemas ¶

func WithMaxCachedSchemas(maxCachedSchemas int) Option

WithMaxCachedSchemas sets the maximum number of JSON schemas to cache. Set to 0 to use the default (1024).

Example:

validation.MustNew(validation.WithMaxCachedSchemas(2048))

func WithMaxErrors ¶

func WithMaxErrors(maxErrors int) Option

WithMaxErrors limits the number of errors returned. Set to 0 for unlimited errors (default).

Example:

validator.Validate(ctx, &req, WithMaxErrors(10))

func WithMaxFields ¶

func WithMaxFields(maxFields int) Option

WithMaxFields sets the maximum number of fields to validate in partial mode. It prevents pathological inputs with extremely large presence maps. Set to 0 to use the default (10000).

Example:

validator.Validate(ctx, &req, WithMaxFields(5000), WithPartial(true))

func WithMessageFunc ¶ added in v0.5.0

func WithMessageFunc(tag string, fn MessageFunc) Option

WithMessageFunc sets a dynamic message generator for a parameterized tag. Use for tags like "min", "max", "len", "oneof" that include parameters.

Example:

validator := validation.MustNew(
    validation.WithMessageFunc("min", func(param string, kind reflect.Kind) string {
        if kind == reflect.String {
            return fmt.Sprintf("too short (min %s chars)", param)
        }
        return fmt.Sprintf("too small (min %s)", param)
    }),
)

func WithMessages ¶ added in v0.5.0

func WithMessages(messages map[string]string) Option

WithMessages sets static error messages for validation tags. Messages override the default English messages for specified tags. Unspecified tags continue to use defaults.

Example:

validator := validation.MustNew(
    validation.WithMessages(map[string]string{
        "required": "cannot be empty",
        "email":    "invalid email format",
    }),
)

func WithPartial ¶

func WithPartial(partial bool) Option

WithPartial enables partial update validation mode (for PATCH requests). It validates only present fields and ignores "required" constraints for absent fields.

Example:

validator.Validate(ctx, &req, WithPartial(true), WithPresence(presenceMap))

func WithPresence ¶

func WithPresence(presence PresenceMap) Option

WithPresence sets the presence map for partial validation. The PresenceMap tracks which fields were provided in the request body. Use ComputePresence to create a PresenceMap from raw JSON.

Example:

presence, _ := ComputePresence(rawJSON)
validator.Validate(ctx, &req, WithPresence(presence), WithPartial(true))

func WithRedactor ¶

func WithRedactor(redactor Redactor) Option

WithRedactor sets a Redactor function to hide sensitive values in error messages. The redactor returns true if the field at the given path should be redacted.

Example:

validator.Validate(ctx, &req, WithRedactor(func(path string) bool {
    return strings.Contains(path, "password") || strings.Contains(path, "token")
}))

func WithRequireAny ¶

func WithRequireAny(require bool) Option

WithRequireAny requires at least one validation strategy to pass when using WithRunAll. When enabled with WithRunAll(true), it causes validation to succeed if at least one strategy produces no errors, even if other strategies fail.

It is useful when you have multiple validation strategies and want to accept the value if it passes any one of them (OR logic).

Example:

// Validate with all strategies, succeed if any one passes
err := validator.Validate(ctx, &req,
    WithRunAll(true),
    WithRequireAny(true),
)

func WithRunAll ¶

func WithRunAll(runAll bool) Option

WithRunAll runs all applicable validation strategies and aggregates errors. By default, validation stops at the first successful strategy.

Example:

validator.Validate(ctx, &req, WithRunAll(true))

func WithStrategy ¶

func WithStrategy(strategy Strategy) Option

WithStrategy sets the validation strategy.

Example:

validator.Validate(ctx, &req, WithStrategy(StrategyTags))

func ComputePresence ¶

func ComputePresence(rawJSON []byte) (PresenceMap, error)

ComputePresence analyzes raw JSON and returns a PresenceMap of present field paths. It enables partial validation where only provided fields are validated.

It returns an empty map (not nil) if rawJSON is empty. It has a maximum recursion depth of 100 to prevent stack overflow from deeply nested JSON structures.

Example:

rawJSON := []byte(`{"user": {"name": "Alice", "age": 0}}`)
presence, err := ComputePresence(rawJSON)
// Returns: {"user": true, "user.name": true, "user.age": true}

Errors:

• Returns error if rawJSON is not valid JSON

package main

import (
	"fmt"

	"rivaas.dev/validation"
)

func main() {
	rawJSON := []byte(`{
		"user": {
			"name": "Alice",
			"age": 30
		},
		"items": [
			{"id": 1, "name": "Item 1"},
			{"id": 2}
		]
	}`)

	presence, err := validation.ComputePresence(rawJSON)
	if err != nil {
		if _, printErr := fmt.Printf("Error: %v\n", err); printErr != nil {
			panic(printErr)
		}

		return
	}

	// Check if specific paths are present
	if _, err = fmt.Printf("user.name present: %v\n", presence.Has("user.name")); err != nil {
		panic(err)
	}
	if _, err = fmt.Printf("user.email present: %v\n", presence.Has("user.email")); err != nil {
		panic(err)
	}
	if _, err = fmt.Printf("items.0.name present: %v\n", presence.Has("items.0.name")); err != nil {
		panic(err)
	}
	if _, err = fmt.Printf("items.1.name present: %v\n", presence.Has("items.1.name")); err != nil {
		panic(err)
	}

	// Get leaf paths (fields that aren't prefixes of others)
	leaves := presence.LeafPaths()
	// Sort for consistent output in example
	if _, err = fmt.Printf("Leaf paths count: %d\n", len(leaves)); err != nil {
		panic(err)
	}
	if _, err = fmt.Printf("Sample leaf: %s\n", leaves[0]); err != nil {
		panic(err)
	}

}

Output:

user.name present: true
user.email present: false
items.0.name present: true
items.1.name present: false
Leaf paths count: 5
Sample leaf: items.0.id

func MustNew ¶ added in v0.2.0

func MustNew(opts ...Option) *Validator

MustNew creates a Validator with the given options. Panics if configuration is invalid.

Use in main() or init() where panic on startup is acceptable.

Example:

validator := validation.MustNew(
    validation.WithRedactor(sensitiveRedactor),
    validation.WithMaxErrors(10),
)

package main

import (
	"context"
	"fmt"

	"rivaas.dev/validation"
)

func main() {
	// MustNew panics if configuration is invalid - suitable for use in main() or init()
	validator := validation.MustNew(
		validation.WithMaxErrors(10),
	)

	type User struct {
		Name string `json:"name" validate:"required"`
	}

	user := User{Name: "Alice"}
	if err := validator.Validate(context.Background(), &user); err != nil {
		if _, printErr := fmt.Printf("Validation failed: %v\n", err); printErr != nil {
			panic(printErr)
		}
	} else {
		if _, printErr := fmt.Println("User is valid"); printErr != nil {
			panic(printErr)
		}
	}
}

Output:

User is valid

func New ¶ added in v0.2.0

func New(opts ...Option) (*Validator, error)

New creates a Validator with the given options. New returns an error if configuration is invalid (e.g., negative maxErrors).

See Option for available configuration options.

Example:

validator, err := validation.New(
    validation.WithMaxErrors(10),
    validation.WithRedactor(sensitiveRedactor),
)
if err != nil {
    return fmt.Errorf("failed to create validator: %w", err)
}

package main

import (
	"context"
	"fmt"

	"rivaas.dev/validation"
)

func main() {
	// Create a validator with custom configuration
	validator, err := validation.New(
		validation.WithMaxErrors(5),
		validation.WithRedactor(func(path string) bool {
			return path == "password" || path == "token"
		}),
	)
	if err != nil {
		if _, printErr := fmt.Printf("Failed to create validator: %v\n", err); printErr != nil {
			panic(printErr)
		}

		return
	}

	type User struct {
		Email string `json:"email" validate:"required,email"`
	}

	user := User{Email: "[email protected]"}
	if validateErr := validator.Validate(context.Background(), &user); validateErr != nil {
		if _, err = fmt.Printf("Validation failed: %v\n", validateErr); err != nil {
			panic(err)
		}
	} else {
		if _, err = fmt.Println("Validation passed"); err != nil {
			panic(err)
		}
	}
}

Output:

Validation passed